From 7d3f8b175c3efc218490f7562cbfc595cfab19dc Mon Sep 17 00:00:00 2001 From: Lea Verou Date: Fri, 20 Dec 2024 17:44:10 -0500 Subject: [PATCH] Separate native styles page for elements that correspond to a separate WA component --- docs/_utils/filters.js | 29 +++++++++++ docs/docs/components/checkbox.md | 3 +- docs/docs/components/radio.md | 3 +- docs/docs/components/range.md | 3 +- docs/docs/components/select.md | 4 +- docs/docs/components/textarea.md | 5 +- docs/docs/native/button.md | 3 +- docs/docs/native/checkbox.md | 89 ++++++++++++++++++++++++++++++++ docs/docs/native/content.md | 2 +- docs/docs/native/details.md | 2 +- docs/docs/native/dialog.md | 3 +- docs/docs/native/index.md | 23 ++++----- docs/docs/native/input.md | 54 ++----------------- docs/docs/native/lists.md | 2 +- docs/docs/native/native.json | 2 +- docs/docs/native/progress.md | 8 ++- docs/docs/native/radio.md | 76 +++++++++++++++++++++++++++ docs/docs/native/select.md | 35 +++++++++++++ docs/docs/native/slider.md | 53 +++++++++++++++++++ docs/docs/native/table.md | 3 +- docs/docs/native/textarea.md | 37 +++++++++++++ docs/docs/utilities/index.md | 31 ++++------- 22 files changed, 367 insertions(+), 103 deletions(-) create mode 100644 docs/docs/native/checkbox.md create mode 100644 docs/docs/native/radio.md create mode 100644 docs/docs/native/select.md create mode 100644 docs/docs/native/slider.md create mode 100644 docs/docs/native/textarea.md diff --git a/docs/_utils/filters.js b/docs/_utils/filters.js index fe2a65591..367960baf 100644 --- a/docs/_utils/filters.js +++ b/docs/_utils/filters.js @@ -133,3 +133,32 @@ export function sort(arr, keys = ['data.order', 'data.title']) { } }); } + +export function groupByTags(collection, tags) { + let ret = Object.fromEntries(tags.map(tag => [tag, []])); + ret.other = []; + + for (let item of collection) { + let categorized = false; + + for (let tag of tags) { + if (item.data.tags.includes(tag)) { + ret[tag].push(item); + categorized = true; + } + } + + if (!categorized) { + ret.other.push(item); + } + } + + // Remove empty categories + for (let category in ret) { + if (ret[category].length === 0) { + delete ret[category]; + } + } + + return ret; +} diff --git a/docs/docs/components/checkbox.md b/docs/docs/components/checkbox.md index b34179270..57ff73526 100644 --- a/docs/docs/components/checkbox.md +++ b/docs/docs/components/checkbox.md @@ -1,7 +1,8 @@ --- title: Checkbox description: Checkboxes allow the user to toggle an option on or off. -tags: component +tags: forms +native: checkbox --- ```html {.example} diff --git a/docs/docs/components/radio.md b/docs/docs/components/radio.md index cde6ee2b7..7f26fd587 100644 --- a/docs/docs/components/radio.md +++ b/docs/docs/components/radio.md @@ -3,6 +3,7 @@ title: Radio description: Radios allow the user to select a single option from a group. tags: component parent: radio-group +native: radio --- Radios are designed to be used with [radio groups](/docs/components/radio-group). @@ -45,7 +46,7 @@ Use the `disabled` attribute to disable a radio. ``` -## Sizes +### Sizes Add the `size` attribute to the [Radio Group](/docs/components/radio-group) to change the radios' size. diff --git a/docs/docs/components/range.md b/docs/docs/components/range.md index c3db10ce8..b315eacf1 100644 --- a/docs/docs/components/range.md +++ b/docs/docs/components/range.md @@ -1,7 +1,8 @@ --- title: Range description: Ranges allow the user to select a single value within a given range using a slider. -tags: component +tags: forms +native: slider --- ```html {.example} diff --git a/docs/docs/components/select.md b/docs/docs/components/select.md index e4db90431..44b7d5cb7 100644 --- a/docs/docs/components/select.md +++ b/docs/docs/components/select.md @@ -1,8 +1,8 @@ --- title: Select description: Selects allow you to choose items from a menu of predefined options. -tags: component -native: input +tags: forms +native: select --- ```html {.example} diff --git a/docs/docs/components/textarea.md b/docs/docs/components/textarea.md index 6c41b6a1b..4e6970f94 100644 --- a/docs/docs/components/textarea.md +++ b/docs/docs/components/textarea.md @@ -1,7 +1,8 @@ --- title: Textarea description: Textareas collect data from the user and allow multiple lines of text. -tags: component +tags: forms +icon: textarea native: input --- @@ -113,4 +114,4 @@ Textareas can be made to resize both vertically and horizontally when `resize` i ```html {.example} -``` \ No newline at end of file +``` diff --git a/docs/docs/native/button.md b/docs/docs/native/button.md index b5eafe84a..cae3d9bba 100644 --- a/docs/docs/native/button.md +++ b/docs/docs/native/button.md @@ -1,8 +1,7 @@ --- title: Button description: 'Button styles apply your Web Awesome theme to native HTML buttons. Buttons are activated by users to perform actions, such as submitting a form.' -tags: native -layout: element +tags: forms component: button icon: button --- diff --git a/docs/docs/native/checkbox.md b/docs/docs/native/checkbox.md new file mode 100644 index 000000000..0fd173e66 --- /dev/null +++ b/docs/docs/native/checkbox.md @@ -0,0 +1,89 @@ +--- +title: Checkbox +description: Checkboxes allow the user to toggle an option on or off. +tags: forms +component: checkbox +icon: checkbox +elements: + "": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox +--- + +```html {.example} + +``` + +## Examples + +### Checked + +Use the `checked` attribute to activate the checkbox. + +```html {.example} + +``` + + + +### Disabled + +Use the `disabled` attribute to disable the checkbox. + +```html {.example} + +``` + + + +### Custom Validity + +Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string. + +```html {.example} +
+ +
+ +
+ +``` diff --git a/docs/docs/native/content.md b/docs/docs/native/content.md index d29f8bfe3..63fd07ecc 100644 --- a/docs/docs/native/content.md +++ b/docs/docs/native/content.md @@ -1,7 +1,7 @@ --- title: Content description: 'Content styles apply your Web Awesome theme to HTML text content, code, and images.' -tags: native +tags: content layout: element icon: skeleton --- diff --git a/docs/docs/native/details.md b/docs/docs/native/details.md index b26093edb..3e0e4c100 100644 --- a/docs/docs/native/details.md +++ b/docs/docs/native/details.md @@ -1,7 +1,7 @@ --- title: Details description: 'Details styles apply your Web Awesome theme to the HTML `
` element. Details show a brief summary and expand to show additional content.' -tags: native +tags: apps layout: element component: details icon: details diff --git a/docs/docs/native/dialog.md b/docs/docs/native/dialog.md index 212ea3d2f..4d4309850 100644 --- a/docs/docs/native/dialog.md +++ b/docs/docs/native/dialog.md @@ -1,8 +1,7 @@ --- title: Dialog description: 'Dialog styles apply your Web Awesome theme to the HTML `` element. Dialogs, also called "modals", appear above the page and interrupt a user''s focus.' -tags: native -layout: element +tags: apps icon: dialog elements: "": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog diff --git a/docs/docs/native/index.md b/docs/docs/native/index.md index b358a5e0e..61c65c26e 100644 --- a/docs/docs/native/index.md +++ b/docs/docs/native/index.md @@ -2,12 +2,23 @@ title: Native Styles description: Native Styles use your theme to style native HTML elements to match the look and feel of Web Awesome components. layout: page-outline +categories: ['forms', 'apps', 'content'] +override:tags: [] --- Web Awesome works _with_ the platform, rather than trying to reinvent it. If all you need is styles, you don’t need to use new `` elements! We also provide styles that make native HTML elements look good so you can continue using what you know and gradually adopt Web Awesome as you see fit. +
+ {% for category, pages in collections.native | groupByTags(categories) -%} +

{{ category | capitalize }}

+ {%- for page in pages -%} + {% include "page-card.njk" %} + {%- endfor -%} + {%- endfor -%} +
+ ## Installation To use all Web Awesome page styles (including [utilities](/docs/utilities/)), include the following stylesheet in your project: @@ -22,18 +33,6 @@ Or, to _only_ include styles for built-in elements: ``` -## Elements - -
- - - {%- for page in collections.native | sort -%} - {%- if page.fileSlug != 'native' -%} - {% include "page-card.njk" %} - {%- endif -%} - {%- endfor -%} -
- ## Opting Out of Native Styles So you've decided to use Native Styles and now you need to style an element or a part of a page completely differently, what to do? diff --git a/docs/docs/native/input.md b/docs/docs/native/input.md index 1fe936b06..c78f9caf2 100644 --- a/docs/docs/native/input.md +++ b/docs/docs/native/input.md @@ -1,19 +1,13 @@ --- -title: Form Inputs -description: 'Form input styles apply your Web Awesome theme to HTML elements like text fields, checkboxes, and more. Form inputs are interactive, allowing users to enter data or control an interface.' -tags: native -layout: element +title: Input +description: Inputs collect data from the user. +tags: forms icon: input -component: - - input - - select - - textarea - - range +component: input elements: "": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input - " - -``` - -## Choice Inputs - -```html {.example} - -WA Checkbox - - - -WA Radio ``` ## Color Picker @@ -102,27 +82,3 @@ With swatches: ``` -## Sliders - -```html {.example} - - -``` - -## Select Dropdowns - -```html {.example} - - - - Option 1 - Option 2 - Option 3 - -``` diff --git a/docs/docs/native/lists.md b/docs/docs/native/lists.md index 209f27aa5..1e8ed449c 100644 --- a/docs/docs/native/lists.md +++ b/docs/docs/native/lists.md @@ -1,7 +1,7 @@ --- title: Lists description: 'List styles apply your Web Awesome theme to HTML lists, such as bulleted, numbered, or description lists.' -tags: native +tags: content layout: element elements: "
    ": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul diff --git a/docs/docs/native/native.json b/docs/docs/native/native.json index 76360bd52..b077f894f 100644 --- a/docs/docs/native/native.json +++ b/docs/docs/native/native.json @@ -1,4 +1,4 @@ { - "layout": "docs.njk", + "layout": "element.njk", "tags": ["native"] } diff --git a/docs/docs/native/progress.md b/docs/docs/native/progress.md index 465170bbf..b02db4fd5 100644 --- a/docs/docs/native/progress.md +++ b/docs/docs/native/progress.md @@ -1,14 +1,12 @@ --- title: Progress Bar description: Progress bars are used to show the status of an ongoing operation. -tags: native -layout: element +tags: apps +icon: progress-bar status: experimental -component: - - progress-bar +component: progress-bar elements: "": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress -icon: progress-bar --- diff --git a/docs/docs/native/radio.md b/docs/docs/native/radio.md new file mode 100644 index 000000000..d89c6309e --- /dev/null +++ b/docs/docs/native/radio.md @@ -0,0 +1,76 @@ +--- +title: Radio +description: Radios allow the user to select a single option from a group. +tags: forms +icon: radio-group +component: radio +elements: + "": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio +--- + + + +```html {.example} + + +``` + +## Examples + +### Initial Value + +To set the initial value and checked state, use the `checked` attribute on the corresponding radio. + +```html {.example} + + + +``` + +### Disabled + +Use the `disabled` attribute to disable a radio. + +```html {.example} + + + +``` + +### Sizes + +Use the [size utilities](/docs/utilities/size) to change the radios' size. + +```html {.example} + + +
    + + +
    + + +``` diff --git a/docs/docs/native/select.md b/docs/docs/native/select.md new file mode 100644 index 000000000..77cb097cd --- /dev/null +++ b/docs/docs/native/select.md @@ -0,0 +1,35 @@ +--- +title: Select +description: Selects allow you to choose items from a menu of predefined options. +tags: forms +icon: select +component: select +elements: + " + + + + + +``` + +## Examples + +### Appearance + +Use the [appearence utilities](/docs/utilities/appearance/) to change the select's visual appearance. + +```html {.example} + +``` diff --git a/docs/docs/native/slider.md b/docs/docs/native/slider.md new file mode 100644 index 000000000..4bbce4ba8 --- /dev/null +++ b/docs/docs/native/slider.md @@ -0,0 +1,53 @@ +--- +title: Slider +description: Sliders allow the user to select a single value within a given range using a slider. +tags: forms +layout: element +icon: range +component: range +elements: + "": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/range +--- + +```html {.example} + +``` + +### Min, Max, and Step + +Use the `min` and `max` attributes to set the range's minimum and maximum values, respectively. The `step` attribute determines the value's interval when increasing and decreasing. + +```html {.example} + +``` + +### Disabled + +Use the `disabled` attribute to disable a slider. + +```html {.example} + +``` + + diff --git a/docs/docs/native/table.md b/docs/docs/native/table.md index e5e1fff37..3b88834ab 100644 --- a/docs/docs/native/table.md +++ b/docs/docs/native/table.md @@ -1,8 +1,7 @@ --- title: Table description: 'Table styles apply your Web Awesome theme to the HTML table content. Tables structure data in rows and columns, making it easy to look up information in a complex data set.' -tags: native -layout: element +tags: content elements: "": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table --- diff --git a/docs/docs/native/textarea.md b/docs/docs/native/textarea.md new file mode 100644 index 000000000..12440a20a --- /dev/null +++ b/docs/docs/native/textarea.md @@ -0,0 +1,37 @@ +--- +title: Textarea +description: Textareas collect data from the user and allow multiple lines of text. +tags: forms +icon: textarea +component: textarea +elements: + " +``` + +### Placeholders + +Use the `placeholder` attribute to add a placeholder. + +```html {.example} + +``` + +### Appearance + +Use the [appearence utilities](/docs/utilities/appearance/) to change the textarea's visual appearance. + +```html {.example} + +``` + +### Expand with Content + +You can use `field-sizing: content` in [browsers that support it](https://caniuse.com/mdn-css_properties_field-sizing) to make the textarea grow as the user types: + +```html {.example} + +``` diff --git a/docs/docs/utilities/index.md b/docs/docs/utilities/index.md index 061d5a6b0..bd30b9c1e 100644 --- a/docs/docs/utilities/index.md +++ b/docs/docs/utilities/index.md @@ -3,8 +3,19 @@ title: Style Utilities description: Web Awesome provides a few style utilities to customize styles in ways that cannot necessarily be described by semantic HTML. Some of these correspond to component attributes, but we also expose utility classes so you can apply these styles to native elements too. layout: page-outline +override:tags: [] +categories: ["layout"] --- +
    + {% for category, pages in collections.utilities | groupByTags(categories) -%} +

    {{ category | capitalize }}

    + {%- for page in pages -%} + {% include "page-card.njk" %} + {%- endfor -%} + {%- endfor -%} +
    + ## Installation To use all Web Awesome page styles (including [native styles](/docs/native/)), include the following stylesheet in your project: @@ -20,23 +31,3 @@ Or, to _only_ include utilities: ``` You can also include individual utilities following the instructions in their pages. - -
    -

    Layout Utilities

    - - {%- for page in collections.utilities | sort -%} - {%- if page.fileSlug != 'native' and 'layout' in page.data.tags -%} - {% include "page-card.njk" %} - {%- endif -%} - {%- endfor -%} -
    - -
    -

    Other Utilities

    - - {%- for page in collections.utilities | sort -%} - {%- if page.fileSlug != 'native' and not ('layout' in page.data.tags) -%} - {% include "page-card.njk" %} - {%- endif -%} - {%- endfor -%} -