opui-css 5.4.2 → 6.0.0-rc.1

package/skills/opui/references/index.md

@@ -0,0 +1,89 @@
+# References
+
+Guides: `getting-started.md` (setup, with a section per framework), `theming.md` (colors, scopes, density, spacing, corners, fonts, elevation, motion and contrast) and `customizing.md` (the `theme.custom` layer and component properties).
+
+Each component reference covers HTML, Astro, React, Svelte and Vue: the parts, props, classes, slots and notes they share, the component properties and theme tokens, then a section per framework with its import line, slots, hydration and an example.
+
+| Component | File | Description |
+| --- | --- | --- |
+| Accordion | `accordion.md` | Lets you show and hide content, on its own or as a group. |
+| Anchor | `anchor.md` | A structural primitive to enable CSS Anchor Positioning on stuff. |
+| Avatar | `avatar.md` | Avatars show a person or entity as an image, initials or icon. |
+| Badge | `badge.md` | Badges attach a small count or status dot to another element. |
+| Button | `button.md` | Buttons allow users to take actions, and make choices, with a single tap. |
+| Button group | `button-group.md` | Groups related buttons by wrapping them with class="ui-button-group" and role="group". |
+| Callout | `callout.md` | Callouts call out for user attention. Should be part of the flow and used without interrupting the user's task. |
+| Card | `card.md` | The card is extremely versatile and can be used on its own, or as a building block for accordions, dialogs and more. |
+| Carousel | `carousel.md` | A scrolling list with snap points, buttons and markers. |
+| Checkbox | `checkbox.md` | Use a Checkbox for choices that are submitted with a form. For a setting that applies right away, use a Switch, and for options in a toolbar a Toggle. See also: Checkbox field group. |
+| Chip | `chip.md` | Chips are compact elements that represent an input, attribute, or action. Use them for filters, tags and choices. For the main action, like Save or Send, use a Button. |
+| Description list | `description-list.md` | Description lists are used to display a list of terms and their descriptions. |
+| Dialog | `dialog.md` | A minimally styled window overlaid on the main content. By design the Dialog is minimal with zero content to allow for both modal and non-modal use. |
+| Divider | `divider.md` | It's just a line. |
+| Drawer | `drawer.md` | Slides in from the sides, top or bottom of the screen. Good for navigation, filters and side content. For a question or a short task that needs the user's full attention, use a Dialog. |
+| Form | `form.md` | Spacing and grouping for form fields. |
+| Layout | `layout.md` | Five classes for the space between components: .ui-layout-column, .ui-layout-row, .ui-layout-grid, .ui-layout-media and .ui-layout-container. Put them on wrapper elements, such as div, section or ul. They sit in the utils layer, so on a component they replace its own layout. Their gaps come from the --ui-space-* scale, so they follow --ui-space-scale. |
+| List | `list.md` | Lists are continuous, vertical indexes of text and images and video. Use lists to help users find a specific item and act on it. |
+| Menu | `menu.md` | A popover list of actions or links. |
+| Progress | `progress.md` | See also: Spinner. |
+| Radio | `radio.md` | See also: Form documentation. |
+| Range | `range.md` | Range lets users pick a number by sliding a thumb along a track. |
+| Select | `select.md` | Leverages the List component to provide markup for the Select popover. Use a Select to pick a value in a form. For actions, use a Menu. |
+| Spinner | `spinner.md` | Add it to an element with aria-busy="true". Spinners are always indeterminate. See also: Progress bar. |
+| Switch | `switch.md` | Use a Switch for a setting that applies right away. Use a Checkbox for choices that are submitted with a form, and a Toggle for options in a toolbar. See also: Switch field group. |
+| Table | `table.md` | Displays tabular data. Basic tables with row and column headers, and optional captions and footers. |
+| Tabs | `tabs.md` | The Tabs are radio inputs and the Panels are just divs that show and hide based on the radio inputs' :checked state. Use Tabs to switch between panels of content. To pick an option, like a list or grid view, use a Toggle group. |
+| Text field | `text-field.md` | An input for single-line text data. Basic text fields with labels, field descriptions, and validation states. |
+| Textarea | `textarea.md` | An input for multi-line text data. Basic textareas with labels, supporting text, and validation states. |
+| Toggle | `toggle.md` | Toggle buttons and toggle groups switch options on and off, alone or as a set. |
+| Tooltip | `tooltip.md` | Built on top of Anchor. |
+| Typography | `typography.md` | Styles for headings, body text, and other text content. Use util classes anywhere or wrap content in .ui-rich-text. |
+
+Components documented on another component's page:
+
+| Component | File |
+| --- | --- |
+| AccordionActions | `accordion.md` |
+| AccordionContent | `accordion.md` |
+| AccordionSummary | `accordion.md` |
+| AnchorContent | `anchor.md` |
+| AvatarGroup | `avatar.md` |
+| CalloutContent | `callout.md` |
+| CalloutIcon | `callout.md` |
+| CardActions | `card.md` |
+| CardContent | `card.md` |
+| CardHeader | `card.md` |
+| CheckboxInput | `checkbox.md` |
+| DescriptionListDescription | `description-list.md` |
+| DescriptionListItem | `description-list.md` |
+| DescriptionListTerm | `description-list.md` |
+| DialogContent | `dialog.md` |
+| DialogFooter | `dialog.md` |
+| DialogHeader | `dialog.md` |
+| DialogTitle | `dialog.md` |
+| DrawerContent | `drawer.md` |
+| DrawerFooter | `drawer.md` |
+| DrawerHeader | `drawer.md` |
+| DrawerTitle | `drawer.md` |
+| FieldDescription | `form.md` |
+| FieldGroup | `form.md` |
+| FieldLegend | `form.md` |
+| Fieldset | `form.md` |
+| ListItem | `list.md` |
+| RadioInput | `radio.md` |
+| SwitchInput | `switch.md` |
+| TableBody | `table.md` |
+| TableCaption | `table.md` |
+| TableCell | `table.md` |
+| TableColumn | `table.md` |
+| TableColumnGroup | `table.md` |
+| TableFoot | `table.md` |
+| TableHead | `table.md` |
+| TableHeaderCell | `table.md` |
+| TableRow | `table.md` |
+| TabsItem | `tabs.md` |
+| TabsLabel | `tabs.md` |
+| TabsPanel | `tabs.md` |
+| ToggleButton | `toggle.md` |
+| ToggleGroup | `toggle.md` |
+| TooltipContent | `tooltip.md` |

package/skills/opui/references/layout.md

@@ -0,0 +1,161 @@
+# Layout
+
+Five classes for the space between components: .ui-layout-column, .ui-layout-row, .ui-layout-grid, .ui-layout-media and .ui-layout-container. Put them on wrapper elements, such as div, section or ul. They sit in the utils layer, so on a component they replace its own layout. Their gaps come from the --ui-space-* scale, so they follow --ui-space-scale.
+
+- CSS: `opui-css/css/components/layout.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/layout.md), [Astro](https://open-props-ui.netlify.app/astro/components/layout.md), [React](https://open-props-ui.netlify.app/react/components/layout.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/layout.md), [Vue](https://open-props-ui.netlify.app/vue/components/layout.md).
+
+## Layout (CSS only)
+
+### Parts
+
+- `.ui-layout-column, .ui-layout-row, .ui-layout-grid, .ui-layout-media, .ui-layout-container` (root): Any element. The classes only set its layout.
+
+### Classes
+
+- Column: `.ui-layout-column`. A column with even space between its children.
+- Container: `.ui-layout-container`. Centers its content and caps its width.
+- Grid: `.ui-layout-grid`. Columns that fill the width and wrap. On a `ul` or `ol` it also drops the list bullets and margins, and a `.ui-card` in each `li` fills its cell.
+- Media: `.ui-layout-media`. A media object: a fixed-size start, such as an avatar, next to text that fills the rest and truncates.
+- Row: `.ui-layout-row`. A wrapping row with its children centered on one line. On a `ul` or `ol` it also drops the list bullets and margins.
+- Sizes: `large` (`.ui-large`), `medium` (default), `small` (`.ui-small`), `x-small` (`.ui-x-small`). The space between children of `.ui-layout-column`, `.ui-layout-row`, `.ui-layout-grid` and `.ui-layout-media`.
+- Spread: `.ui-spread`. Pushes the children of `.ui-layout-row` to its two ends, for a page header with a heading group and its actions.
+
+### Notes
+
+- Astro and Vue: Add the classes to elements in your templates.
+- React and Svelte: Add the classes to elements in your markup.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### layout.css
+
+- `--_gap`: Space between the children of `.ui-layout-column`, `.ui-layout-row`, `.ui-layout-grid` and `.ui-layout-media`. Defaults to `--ui-space-3`, set by the size classes.
+- `--_justify-content`: How `.ui-layout-row` distributes its children along the row, such as `flex-end`. `.ui-spread` sets it to `space-between`.
+- `--_max-inline-size`: Maximum width of `.ui-layout-container`.
+- `--_min-inline-size`: Narrowest column of `.ui-layout-grid`. Columns are added while they fit at this width.
+- `--_padding-inline`: Inline padding of `.ui-layout-container`. Defaults to `--ui-space-4`.
+
+## Theme tokens
+
+The stylesheets read `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-4` and `--ui-space-5`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Column
+
+```html
+<div class="ui-layout-column">
+  <div class="ui-card ui-outlined">
+    <div class="ui-content">First</div>
+  </div>
+  <div class="ui-card ui-outlined">
+    <div class="ui-content">Second</div>
+  </div>
+  <div class="ui-card ui-outlined">
+    <div class="ui-content">Third</div>
+  </div>
+</div>
+```
+
+## Astro
+
+There is no Astro component. Use the classes in your markup.
+
+### Example: Column
+
+```astro
+---
+import { Card, CardContent } from "opui-css/astro"
+---
+
+<div class="ui-layout-column">
+  <Card variant="outlined">
+    <CardContent>First</CardContent>
+  </Card>
+  <Card variant="outlined">
+    <CardContent>Second</CardContent>
+  </Card>
+  <Card variant="outlined">
+    <CardContent>Third</CardContent>
+  </Card>
+</div>
+```
+
+## React
+
+There is no React component. Use the classes in your markup.
+
+### Example: Column
+
+```tsx
+import { Card, CardContent } from "opui-css/react"
+
+export default function Column() {
+  return (
+    <div className="ui-layout-column">
+      <Card variant="outlined">
+        <CardContent>First</CardContent>
+      </Card>
+      <Card variant="outlined">
+        <CardContent>Second</CardContent>
+      </Card>
+      <Card variant="outlined">
+        <CardContent>Third</CardContent>
+      </Card>
+    </div>
+  )
+}
+```
+
+## Svelte
+
+There is no Svelte component. Use the classes in your markup.
+
+### Example: Column
+
+```svelte
+<script lang="ts">
+  import { Card, CardContent } from "opui-css/svelte"
+</script>
+
+<div class="ui-layout-column">
+  <Card variant="outlined">
+    <CardContent>First</CardContent>
+  </Card>
+  <Card variant="outlined">
+    <CardContent>Second</CardContent>
+  </Card>
+  <Card variant="outlined">
+    <CardContent>Third</CardContent>
+  </Card>
+</div>
+```
+
+## Vue
+
+There is no Vue component. Use the classes in your markup.
+
+### Example: Column
+
+```vue
+<script setup lang="ts">
+import { Card, CardContent } from "opui-css/vue"
+</script>
+
+<template>
+  <div class="ui-layout-column">
+    <Card variant="outlined">
+      <CardContent>First</CardContent>
+    </Card>
+    <Card variant="outlined">
+      <CardContent>Second</CardContent>
+    </Card>
+    <Card variant="outlined">
+      <CardContent>Third</CardContent>
+    </Card>
+  </div>
+</template>
+```

package/skills/opui/references/list.md

@@ -0,0 +1,216 @@
+# List
+
+Lists are continuous, vertical indexes of text and images and video. Use lists to help users find a specific item and act on it.
+
+- CSS: `opui-css/css/components/list.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/list.md), [Astro](https://open-props-ui.netlify.app/astro/components/list.md), [React](https://open-props-ui.netlify.app/react/components/list.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/list.md), [Vue](https://open-props-ui.netlify.app/vue/components/list.md).
+
+## List
+
+### Parts
+
+- `ul.ui-list` (root): Container element.
+- `<li>` (`ListItem`): A list item.
+
+### Props and modifiers
+
+- `bordered`: `boolean`, `.ui-bordered`. Adds a border between list items.
+- `dense`: `boolean`, `.ui-dense`. Packs the items tighter.
+- `flush`: `boolean`, `.ui-flush`. Removes the inline padding.
+- `variant`: `"filled"` (default), `"tonal"` (`.ui-tonal`), `"transparent"` (`.ui-transparent`). The variant to use. The default `filled` list uses the filled surface.
+
+### Slots
+
+- `default`: The list items.
+
+## ListItem
+
+### Parts
+
+- `<li>` (root): The list item.
+- `<a>, <button>, <label>` (prop `as`, prop `href`, prop `type`): The clickable row, rendered by `as`, `href` or `type`.
+- `.ui-start` (slot `start`): Optional content at the start, such as an icon or avatar.
+- `.ui-text`: The text content.
+- `<p>` (prop `label`, slot `label`): The label, the first paragraph.
+- `<p>` (prop `description`, slot `description`): Supporting text, the second paragraph.
+- `.ui-end` (slot `end`): Optional content at the end, such as a value or an action.
+
+### Props and modifiers
+
+- `as`: `"a" | "button"`. The element to render inside the `<li>`: `"a"` or `"button"`. Defaults to `"a"` when `href` is set, and to nothing otherwise, so a static item is a bare `<li>`. A `<button>` gets `type="button"`.
+- `borderTop`: `boolean`, `.ui-border-top`. Adds a border above the item.
+- `color`: `"critical"` (`.ui-critical`). Optional colors. `critical` marks a destructive item in a [Menu](/components/menu).
+- `disabled`: `boolean`. Disables a button item. A link item drops its `href` and gets `aria-disabled="true"` instead.
+- `for` (Astro, Svelte and Vue): `string`. The `for` attribute of the `<label>` when `type` is set.
+- `href`: `string`. The link to use. Renders an `<a>` inside the `<li>`.
+- `htmlFor` (React): `string`. The `for` attribute of the `<label>` when `type` is set, as `htmlFor` like on the element.
+- `inset`: `boolean`, `.ui-inset`. Aligns the text with items that have start content.
+- State (HTML): `current` (`[aria-current="page"]`), `disabled` (`[disabled]`), `disabledLink` (`[aria-disabled="true"]`). Highlights the current item, or dims a disabled one. Set it on the `<a>`, `<button>` or `<label>`.
+- `type`: `"checkbox"` (`label.ui-checkbox`), `"radio"` (`label.ui-radio`), `"switch"` (`label.ui-switch`). Wraps the content in a `<label>` for a checkbox, radio or switch. Can't be combined with `as` or `href`.
+
+### Slots
+
+- `default`: More content inside `.ui-text`, after the label and description, or all the content when there's neither.
+- `submenu`: A submenu `Menu`, rendered inside the `<li>` after the element set by `as`.
+
+### Notes
+
+- HTML: To make the item interactive, wrap the content in an `<a>`, `<button>` or `<label>`.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### list.css
+
+- `--_bg-color`: Background of the list and its items. Defaults to `--ui-surface-filled`, `.ui-transparent` and `.ui-tonal` set it.
+- `--_description-text-color`: Text color of the description paragraph in an item. `--ui-text-subtle`, and `--ui-on-selected` on a selected or current row when a theme sets it.
+- `--_divider-border-color`: Color of the lines between items in `.ui-bordered` and on `.ui-border-top`. Defaults to `--ui-border-color`, mixed with 20% `--ui-text-strong` in `.ui-tonal`.
+- `--_hover-bg-color`: Background of hovered items, from `--ui-primary`.
+- `--_item-gap`: Gap between the content of an item. Smaller in `.ui-dense`.
+- `--_item-padding-inline`: Horizontal padding of items, headings and options. `--ui-list-item-padding-inline`, or `--ui-space-3` when a theme leaves it unset.
+- `--_radius`: The corner radius of a `.ui-list`. Defaults to `--ui-radius`, and `0` when the list is a direct child of a `Card`, `Accordion` or `Dialog`, which round and clip it themselves.
+- `--_selected-bg-color`: Background of selected and current items and options. `--ui-selected` when the theme sets it, otherwise `--ui-primary` at `--ui-state-active-alpha-accent`, stronger than `--_hover-bg-color`. With more contrast it is `--_hover-bg-color`, so the text keeps 7:1, and the bar marks the row.
+- `--_selected-indicator-bg-color`: Color of the bar on the start edge of selected and current items and options, which marks them without relying on the fill. Defaults to `--ui-selected-strong`.
+- `--_selected-indicator-size`: Width of the bar on selected and current items. Defaults to `--ui-border-width-thick`.
+- `--_separator-gap`: Space around the lines between items in `.ui-bordered` and on `.ui-border-top`. Smaller in `.ui-dense`.
+- `--_start-image-size`: Width of a square image in `.ui-start`.
+- `--_start-size`: Maximum size of leading and trailing icons, and the indent of `.ui-inset` items. Smaller in `.ui-dense`.
+- `--_start-video-size`: Height of a video in `.ui-start`, which keeps a 16:9 ratio.
+
+Outputs: `--_selected-shadow`.
+
+## Theme tokens
+
+The stylesheets read `--ui-border-color`, `--ui-border-color-on-filled`, `--ui-border-color-on-raised`, `--ui-border-color-raised`, `--ui-border-width`, `--ui-border-width-thick`, `--ui-choice-size-small`, `--ui-control-size`, `--ui-control-size-small`, `--ui-critical`, `--ui-critical-text`, `--ui-disabled-opacity`, `--ui-duration-slow`, `--ui-ease-enter`, `--ui-ease-exit`, `--ui-field-border-color-on-filled`, `--ui-field-border-color-on-raised`, `--ui-focus-ring-inset`, `--ui-font-code`, `--ui-font-size-caption`, `--ui-font-size-small`, `--ui-font-weight-bold`, `--ui-font-weight-normal`, `--ui-icon-size`, `--ui-icon-size-small`, `--ui-line-height`, `--ui-list-item-padding-inline`, `--ui-menu-radius`, `--ui-motion`, `--ui-on-selected`, `--ui-primary`, `--ui-primary-text`, `--ui-radius`, `--ui-selected`, `--ui-selected-strong`, `--ui-shadow-overlay`, `--ui-space-1`, `--ui-space-2`, `--ui-space-3`, `--ui-space-6`, `--ui-state-active-alpha-accent`, `--ui-state-hover-alpha-accent`, `--ui-surface-elevated`, `--ui-surface-filled`, `--ui-surface-tonal`, `--ui-switch-thumb-size-small`, `--ui-switch-track-block-size-small`, `--ui-switch-track-inline-size-small`, `--ui-text`, `--ui-text-strong` and `--ui-text-subtle`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Basics
+
+```html
+<ul class="ui-list">
+  <li>
+    <div class="ui-text">
+      <p>Headline</p>
+    </div>
+  </li>
+  <li>
+    <div class="ui-text">
+      <p>Headline</p>
+      <p>
+        Supporting text that truly is quite long enough to fill up multiple
+        lines.
+      </p>
+    </div>
+  </li>
+  <li>
+    <div class="ui-text">
+      <p>Trailing supporting text</p>
+    </div>
+    <div class="ui-end">100+</div>
+  </li>
+</ul>
+```
+
+## Astro
+
+`import { List, ListItem } from "opui-css/astro"`
+
+- `ListItem` named slots: `description`, `end`, `label`, `start` and `submenu`. Fill one with `slot="description"` on a child.
+
+### Example: Basics
+
+```astro
+---
+import { List, ListItem } from "opui-css/astro"
+---
+
+<List>
+  <ListItem label="Headline" />
+  <ListItem
+    label="Headline"
+    description="Supporting text that truly is quite long enough to fill up multiple lines."
+  />
+  <ListItem label="Trailing supporting text">
+    <Fragment slot="end">100+</Fragment>
+  </ListItem>
+</List>
+```
+
+## React
+
+`import { List, ListItem } from "opui-css/react"`
+
+- `ListItem` slot props (`ReactNode`): `children`, `description`, `end`, `label`, `start` and `submenu`.
+
+### Example: Basics
+
+```tsx
+import { List, ListItem } from "opui-css/react"
+
+export default function Basics() {
+  return (
+    <List>
+      <ListItem label="Headline" />
+      <ListItem
+        label="Headline"
+        description="Supporting text that truly is quite long enough to fill up multiple lines."
+      />
+      <ListItem label="Trailing supporting text" end="100+" />
+    </List>
+  )
+}
+```
+
+## Svelte
+
+`import { List, ListItem } from "opui-css/svelte"`
+
+- `ListItem` slot snippets: `children`, `description`, `end`, `label`, `start` and `submenu`.
+
+### Example: Basics
+
+```svelte
+<script lang="ts">
+  import { List, ListItem } from "opui-css/svelte"
+</script>
+
+<List>
+  <ListItem label="Headline" />
+  <ListItem
+    label="Headline"
+    description="Supporting text that truly is quite long enough to fill up multiple lines."
+  />
+  <ListItem label="Trailing supporting text">
+    {#snippet end()}100+{/snippet}
+  </ListItem>
+</List>
+```
+
+## Vue
+
+`import { List, ListItem } from "opui-css/vue"`
+
+- `ListItem` named slots: `description`, `end`, `label`, `start` and `submenu`. Fill one with `<template #description>`.
+
+### Example: Basics
+
+```vue
+<script setup lang="ts">
+import { List, ListItem } from "opui-css/vue"
+</script>
+
+<template>
+  <List>
+    <ListItem label="Headline" />
+    <ListItem
+      label="Headline"
+      description="Supporting text that truly is quite long enough to fill up multiple lines."
+    />
+    <ListItem label="Trailing supporting text">
+      <template #end>100+</template>
+    </ListItem>
+  </List>
+</template>
+```