From 78939ff8a5596c93c514791b033e39453cdc8038 Mon Sep 17 00:00:00 2001 From: Elson Correia Date: Thu, 3 Oct 2024 17:09:20 -0400 Subject: [PATCH] installation and get started docs --- .../capabilities/function-component.md | 100 ++++++++++++++++++ docs/documentation/get-started.md | 40 +++++++ docs/documentation/installation.md | 51 +++++++++ docs/stylesheets/common.css | 4 + docs/stylesheets/documentation.css | 3 + 5 files changed, 198 insertions(+) diff --git a/docs/documentation/capabilities/function-component.md b/docs/documentation/capabilities/function-component.md index 07a94ca3..c9c241ee 100644 --- a/docs/documentation/capabilities/function-component.md +++ b/docs/documentation/capabilities/function-component.md @@ -7,3 +7,103 @@ layout: document --- ## Function Component + +Markup does not ship with a dedicated component API. Components are simply functions that return a `HTMLTemplate` instance. + +```javascript +const MyButton = () => { + return html` + + `; +} +``` + +It is totally up to you what these functions can do or look like. From the example above, you can simply render your component using the `render` method. + +```javascript +MyButton().render(document.body) +``` + +### Inputs (Props) + +Since its functions, you can take arguments and inject them directly into the template with proper defaults handling. + +```javascript +const Button = ({ + content = "", + disabled = false, + type = "button" +}) => { + return html` + `; +} +``` + +Templates can take raw values or functions that returns some value which can be a `state` or simply a `dynamic value`, in that case, you can have your input type definition use the `StateGetter` type. + +```typescript +enum MyButtonType { + Button = 'button', + Reset = 'reset', + Submit = 'submit' +} + +interface MyButtonProps { + content: unknown; + disabled: boolean | StateGetter + type: MyButtonType | StateGetter +} +``` + +The `StateGetter` allows you to communicate that your component takes function values as input which makes it easier to work with states. + +### Lifecycles + +You can take advantage of both [effect](../state/effect.md) and `html` [lifecycles](../templating/lifecycles.md) to react to things like component mounted, unmounted, and updates to do everything you need. + +```javascript +const ChatMessages = () => { + const [messages, updateMessages] = state([]) + + onUpdate(() => { + // todo: scroll to the bottom to show latest msg + }) + + const onMount = () => { + const controller = new AbortController(); + const signal = controller.signal; + + fetch('...', { signal }) + .then((res) => { + if(!res.ok) throw new Error(res.statusText) + + return res.json() + }) + .then((res) => updateMessages(res.messages)) + .catch(console.error); + + // return a function to be called on unmount + // where you can perform any clean ups + return () => { + controller.abort(); + } + } + + return html` +
    + ${repeat(messages, msg => html`
  • ${msg}
    • +
+ `)} + .onMount(onMount) + .onUpdate(onUpdate) +} +``` + +Markup template has powerful lifecycles and because a function is called once and with power of reactivity, you can encapsulate everything inside the function leaving everything to Markup to manage. diff --git a/docs/documentation/get-started.md b/docs/documentation/get-started.md index 336a7918..c533e3f1 100644 --- a/docs/documentation/get-started.md +++ b/docs/documentation/get-started.md @@ -7,3 +7,43 @@ layout: document --- ## Get Started + +Markup is a plug and play library, which means, you don't need to build or compile it into anything to be able to see what you build. + +Additionally, you can run it on the client and server to produce any type of application. + +### Try it in-Browser + +The simplest way to start is by trying it in-browser, and we have set up few project you can get started with: + +- [Client ToDo App with State Management](https://stackblitz.com/edit/web-platform-lvonxr) (StackBlitz) +- [Client Counter App](https://stackblitz.com/edit/web-platform-ixypdh) (StackBlitz) +- [Client Timer App](https://codepen.io/beforesemicolon/pen/yLQzQZV) (CodePen) +- [Node SSR website](https://stackblitz.com/edit/stackblitz-starters-a6rvq7) (StackBlitz) + +### HTML File + +The simplest way to start is by creating an html file and adding the following content. You can then open it in the browser to see. + +```html + + + + Hello World + + + + + +
+ + + + +``` diff --git a/docs/documentation/installation.md b/docs/documentation/installation.md index 665ca311..b9c71396 100644 --- a/docs/documentation/installation.md +++ b/docs/documentation/installation.md @@ -7,3 +7,54 @@ layout: document --- ## Installation + +Markup is a plug-and-play package that does not need to be built. There is no need to any additional setup or requirements to get started. Simply add it to your project and proceed. + +### Via CDN + +This method is the quickest loading option and can be placed in the head tag of the document. + +```html +