opui-css 5.4.3 → 6.0.0-rc.1

package/skills/opui/references/anchor.md

@@ -0,0 +1,213 @@
+# Anchor
+
+A structural primitive to enable CSS Anchor Positioning on stuff.
+
+- CSS: `opui-css/css/components/anchor.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/anchor.md), [Astro](https://open-props-ui.netlify.app/astro/components/anchor.md), [React](https://open-props-ui.netlify.app/react/components/anchor.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/anchor.md), [Vue](https://open-props-ui.netlify.app/vue/components/anchor.md).
+
+## Anchor
+
+### Parts
+
+- `.ui-anchor` (root): Container element. Scopes the anchor to its content.
+- `& > :first-child`: The content the floating content is anchored to.
+- `.ui-floating` (`AnchorContent`): The floating content.
+
+### Props and modifiers
+
+- `id`: `string`. The id of the root. With `trigger="hover"`, the id of `AnchorContent`. Add `interestfor` with the same id to the trigger. Required with `trigger="hover"`.
+- `positionArea`: `string`, `--ui-anchor-position-area`, default `"self-start self-end"`. Any valid `position-area` value. Controls where the floating content is placed. The `self-` keywords follow the content's own direction, so the placement mirrors in a right-to-left part of a left-to-right page.
+- `trigger`: `"hover"` (`.ui-floating[popover="hint"]`). Shows the floating content on hover and focus with `popover="hint"`. Without it, the content always shows.
+
+### Slots
+
+- `default`: The content to anchor to, followed by `AnchorContent`.
+
+### Notes
+
+- HTML: To show on hover, give `.ui-floating` `popover="hint"` and an id. Add `interestfor` with that id to the trigger.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### anchor.css
+
+- `--_shift-x`: Horizontal shift of `.ui-floating`. Defaults to `0`.
+- `--_shift-y`: Vertical shift of `.ui-floating`. Defaults to `0`.
+
+## HTML
+
+### Example: Always visible
+
+```html
+<span class="ui-anchor" style="--ui-anchor-position-area: inline-end">
+  <button type="button" class="ui-button ui-outlined">Export</button>
+  <span class="ui-floating">
+    <div class="ui-card ui-tonal coach-mark">
+      <div class="ui-content">
+        <strong>New</strong> Export to PDF and CSV from the same menu.
+      </div>
+    </div>
+  </span>
+</span>
+
+<style>
+  .coach-mark {
+    font-size: var(--ui-font-size-body);
+    margin-inline-start: var(--ui-space-2);
+    max-inline-size: 220px;
+  }
+</style>
+```
+
+## Astro
+
+`import { Anchor, AnchorContent } from "opui-css/astro"`
+
+### Example: Always visible
+
+```astro
+---
+import {
+  Anchor,
+  AnchorContent,
+  Button,
+  Card,
+  CardContent,
+} from "opui-css/astro"
+---
+
+<Anchor positionArea="inline-end">
+  <Button variant="outlined">Export</Button>
+  <AnchorContent>
+    <Card variant="tonal" class="coach-mark">
+      <CardContent>
+        <strong>New</strong> Export to PDF and CSV from the same menu.
+      </CardContent>
+    </Card>
+  </AnchorContent>
+</Anchor>
+
+<style>
+  .coach-mark {
+    font-size: var(--ui-font-size-body);
+    margin-inline-start: var(--ui-space-2);
+    max-inline-size: 220px;
+  }
+</style>
+```
+
+## React
+
+`import { Anchor, AnchorContent } from "opui-css/react"`
+
+- Client components (`"use client"`): `Anchor`.
+
+### Example: Always visible
+
+```tsx
+import {
+  Anchor,
+  AnchorContent,
+  Button,
+  Card,
+  CardContent,
+} from "opui-css/react"
+
+export default function AlwaysVisible() {
+  return (
+    <>
+      <Anchor positionArea="inline-end">
+        <Button variant="outlined">Export</Button>
+        <AnchorContent>
+          <Card variant="tonal" className="coach-mark">
+            <CardContent>
+              <strong>New</strong> Export to PDF and CSV from the same menu.
+            </CardContent>
+          </Card>
+        </AnchorContent>
+      </Anchor>
+      <style>{`
+        .coach-mark {
+          font-size: var(--ui-font-size-body);
+          margin-inline-start: var(--ui-space-2);
+          max-inline-size: 220px;
+        }
+      `}</style>
+    </>
+  )
+}
+```
+
+## Svelte
+
+`import { Anchor, AnchorContent } from "opui-css/svelte"`
+
+### Example: Always visible
+
+```svelte
+<script lang="ts">
+  import {
+    Anchor,
+    AnchorContent,
+    Button,
+    Card,
+    CardContent,
+  } from "opui-css/svelte"
+</script>
+
+<Anchor positionArea="inline-end">
+  <Button variant="outlined">Export</Button>
+  <AnchorContent>
+    <Card variant="tonal" class="coach-mark">
+      <CardContent>
+        <strong>New</strong> Export to PDF and CSV from the same menu.
+      </CardContent>
+    </Card>
+  </AnchorContent>
+</Anchor>
+
+<style>
+  :global {
+    .coach-mark {
+      font-size: var(--ui-font-size-body);
+      margin-inline-start: var(--ui-space-2);
+      max-inline-size: 220px;
+    }
+  }
+</style>
+```
+
+## Vue
+
+`import { Anchor, AnchorContent } from "opui-css/vue"`
+
+### Example: Always visible
+
+```vue
+<script setup lang="ts">
+import { Anchor, AnchorContent, Button, Card, CardContent } from "opui-css/vue"
+</script>
+
+<template>
+  <Anchor positionArea="inline-end">
+    <Button variant="outlined">Export</Button>
+    <AnchorContent>
+      <Card variant="tonal" class="coach-mark">
+        <CardContent>
+          <strong>New</strong> Export to PDF and CSV from the same menu.
+        </CardContent>
+      </Card>
+    </AnchorContent>
+  </Anchor>
+</template>
+
+<style>
+.coach-mark {
+  font-size: var(--ui-font-size-body);
+  margin-inline-start: var(--ui-space-2);
+  max-inline-size: 220px;
+}
+</style>
+```

package/skills/opui/references/avatar.md

@@ -0,0 +1,202 @@
+# Avatar
+
+Avatars show a person or entity as an image, initials or icon.
+
+- CSS: `opui-css/css/components/avatar.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/avatar.md), [Astro](https://open-props-ui.netlify.app/astro/components/avatar.md), [React](https://open-props-ui.netlify.app/react/components/avatar.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/avatar.md), [Vue](https://open-props-ui.netlify.app/vue/components/avatar.md).
+
+## Avatar
+
+### Parts
+
+- `.ui-avatar` (root): Container element.
+- `<img>` (prop `src`, prop `alt`): The avatar image.
+
+### Props and modifiers
+
+- `alt`: `string`. Alternative text for the image. Required with `src`. Use an empty string when the name is shown next to it.
+- `as`: `"a" | "button" | "div"`, default `"div"`. The element to render. Defaults to `"a"` with `href`.
+- `disabled`: `boolean`. Disables a button avatar. A link avatar drops its `href` and gets `aria-disabled="true"` instead.
+- `href`: `string`. The link to use. Renders an `<a>`.
+- `shape`: `"circle"` (default), `"rounded"` (`.ui-rounded`), `"squared"` (`.ui-squared`), `"squircle"` (`.ui-squircle`). The shape of the avatar.
+- `size`: `"large"` (`.ui-large`), `"medium"` (default), `"small"` (`.ui-small`), `"x-small"` (`.ui-x-small`). The size of the element.
+- `src`: `string`. The image source. Replaces the content.
+- State (HTML): `button` (`button[disabled]`), `link` (`a[aria-disabled="true"]`). Disables a button avatar. A link avatar, which can't take `disabled`, drops its `href` and takes `aria-disabled="true"` instead.
+
+### Slots
+
+- `default`: Letters or an icon, when there's no image.
+
+## AvatarGroup
+
+### Parts
+
+- `.ui-avatar-group` (root): A group of overlapping avatars.
+
+### Slots
+
+- `default`: The avatars.
+
+### Notes
+
+- HTML: The root needs `role="group"` and an `aria-label`.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### avatar.css
+
+- `--_bg-color`: The background. Defaults to `--ui-primary`. An avatar with an `img` is always transparent.
+- `--_font-size`: The font size of initials. Set by the size classes.
+- `--_icon-size`: The maximum width of an `svg`. Set by `.ui-x-small` and `.ui-small`.
+- `--_margin`: How much avatars in a `.ui-avatar-group` overlap. Set on the group.
+- `--_outline-color`: The ring around each avatar in a `.ui-avatar-group`. Defaults to `--ui-surface`. Set on the group.
+- `--_outline-width`: Width of the ring around each avatar in a `.ui-avatar-group`. Set on the group.
+- `--_size`: The width and height. Defaults to `--ui-control-size`, set by the size classes.
+- `--_text-color`: The text and icon color. Defaults to `--ui-on-primary`.
+
+## Theme tokens
+
+The stylesheets read `--ui-border-width`, `--ui-border-width-thick`, `--ui-control-size`, `--ui-control-size-large`, `--ui-control-size-small`, `--ui-control-size-x-small`, `--ui-disabled-opacity`, `--ui-font-size-caption`, `--ui-font-size-large`, `--ui-font-size-small`, `--ui-icon-size`, `--ui-icon-size-large`, `--ui-icon-size-small`, `--ui-on-primary`, `--ui-primary`, `--ui-radius-round`, `--ui-radius-small`, `--ui-space-2` and `--ui-surface`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Image
+
+```html
+<div class="ui-avatar">
+  <img
+    src="https://images.unsplash.com/photo-1614530606961-c4ce986825c1?w=96&h=96&fit=crop&auto=format"
+    alt="Maya Lind"
+  />
+</div>
+
+<div class="ui-avatar">
+  <img
+    src="https://images.unsplash.com/photo-1672714413950-c9f7c5a45fa1?w=96&h=96&fit=crop&auto=format"
+    alt="Omar Haddad"
+  />
+</div>
+
+<div class="ui-avatar">
+  <img
+    src="https://plus.unsplash.com/premium_photo-1675674458649-0c667500f3cc?w=96&h=96&fit=crop&auto=format"
+    alt="Priya Nair"
+  />
+</div>
+```
+
+## Astro
+
+`import { Avatar, AvatarGroup } from "opui-css/astro"`
+
+### Example: Image
+
+```astro
+---
+import { Avatar } from "opui-css/astro"
+---
+
+<Avatar
+  src="https://images.unsplash.com/photo-1614530606961-c4ce986825c1?w=96&h=96&fit=crop&auto=format"
+  alt="Maya Lind"
+/>
+
+<Avatar
+  src="https://images.unsplash.com/photo-1672714413950-c9f7c5a45fa1?w=96&h=96&fit=crop&auto=format"
+  alt="Omar Haddad"
+/>
+
+<Avatar
+  src="https://plus.unsplash.com/premium_photo-1675674458649-0c667500f3cc?w=96&h=96&fit=crop&auto=format"
+  alt="Priya Nair"
+/>
+```
+
+## React
+
+`import { Avatar, AvatarGroup } from "opui-css/react"`
+
+### Example: Image
+
+```tsx
+import { Avatar } from "opui-css/react"
+
+export default function Image() {
+  return (
+    <>
+      <Avatar
+        src="https://images.unsplash.com/photo-1614530606961-c4ce986825c1?w=96&h=96&fit=crop&auto=format"
+        alt="Maya Lind"
+      />
+
+      <Avatar
+        src="https://images.unsplash.com/photo-1672714413950-c9f7c5a45fa1?w=96&h=96&fit=crop&auto=format"
+        alt="Omar Haddad"
+      />
+
+      <Avatar
+        src="https://plus.unsplash.com/premium_photo-1675674458649-0c667500f3cc?w=96&h=96&fit=crop&auto=format"
+        alt="Priya Nair"
+      />
+    </>
+  )
+}
+```
+
+## Svelte
+
+`import { Avatar, AvatarGroup } from "opui-css/svelte"`
+
+### Example: Image
+
+```svelte
+<script lang="ts">
+  import { Avatar } from "opui-css/svelte"
+</script>
+
+<Avatar
+  src="https://images.unsplash.com/photo-1614530606961-c4ce986825c1?w=96&h=96&fit=crop&auto=format"
+  alt="Maya Lind"
+/>
+
+<Avatar
+  src="https://images.unsplash.com/photo-1672714413950-c9f7c5a45fa1?w=96&h=96&fit=crop&auto=format"
+  alt="Omar Haddad"
+/>
+
+<Avatar
+  src="https://plus.unsplash.com/premium_photo-1675674458649-0c667500f3cc?w=96&h=96&fit=crop&auto=format"
+  alt="Priya Nair"
+/>
+```
+
+## Vue
+
+`import { Avatar, AvatarGroup } from "opui-css/vue"`
+
+### Example: Image
+
+```vue
+<script setup lang="ts">
+import { Avatar } from "opui-css/vue"
+</script>
+
+<template>
+  <Avatar
+    src="https://images.unsplash.com/photo-1614530606961-c4ce986825c1?w=96&h=96&fit=crop&auto=format"
+    alt="Maya Lind"
+  />
+
+  <Avatar
+    src="https://images.unsplash.com/photo-1672714413950-c9f7c5a45fa1?w=96&h=96&fit=crop&auto=format"
+    alt="Omar Haddad"
+  />
+
+  <Avatar
+    src="https://plus.unsplash.com/premium_photo-1675674458649-0c667500f3cc?w=96&h=96&fit=crop&auto=format"
+    alt="Priya Nair"
+  />
+</template>
+```

package/skills/opui/references/badge.md

@@ -0,0 +1,199 @@
+# Badge
+
+Badges attach a small count or status dot to another element.
+
+- CSS: `opui-css/css/components/badge.css` and `opui-css/css/components/anchor.css`.
+- Full docs with every example: [HTML](https://open-props-ui.netlify.app/html/components/badge.md), [Astro](https://open-props-ui.netlify.app/astro/components/badge.md), [React](https://open-props-ui.netlify.app/react/components/badge.md), [Svelte](https://open-props-ui.netlify.app/svelte/components/badge.md), [Vue](https://open-props-ui.netlify.app/vue/components/badge.md).
+
+## Badge
+
+### Parts
+
+- `.ui-badge` (root): Container element.
+- `& > :first-child` (slot `default`): The element the badge is anchored to.
+- `.ui-indicator` (prop `label`, slot `indicator`): The indicator, inside `.ui-floating`. Holds `label`, the visible text with `hideLabel`, or only screen reader text with `dot`.
+
+### Props and modifiers
+
+- `color`: `"critical"` (`.ui-critical`), `"info"` (`.ui-info`), `"neutral"` (`.ui-neutral`), `"success"` (`.ui-success`), `"warning"` (`.ui-warning`). Optional colors.
+- `corner`: `"end-end"` (`.ui-end-end`), `"end-start"` (`.ui-end-start`), `"start-end"` (default), `"start-start"` (`.ui-start-start`). The corner the indicator sits on.
+- `dot`: `boolean`, `.ui-dot`. Renders the indicator as a dot. `label` stays as screen reader text, and the `indicator` slot isn't shown.
+- `hideLabel`: `boolean`, `.ui-indicator > span.ui-sr-only`. Hides `label` visually, for the whole sentence screen readers read, such as "5 unread messages". The `indicator` slot then holds the visible text and is hidden from screen readers.
+- `invisible`: `boolean`, `.ui-invisible`. Hides the indicator.
+
+## Component properties
+
+Set inputs on the component, inline or in your CSS. Outputs follow the variant and state, so never override them.
+
+### badge.css
+
+- `--_border-width`: Border width of the indicator.
+- `--_dot-size`: Width and height of the indicator in `.ui-dot`.
+- `--_ease`: Easing of the indicator fade. Defaults to `--ui-ease-enter`.
+- `--_inset`: Distance of the indicator from the opposite edges. `100%` places it on the corner, round avatars move it onto the circle.
+- `--_motion`: Motion multiplier for the transitions. `0` turns them off.
+- `--_size`: Height and minimum width of the indicator.
+
+Outputs: `--_accent`, `--_bg-color`, `--_border-color`, `--_direction`, `--_duration`, `--_inset-block`, `--_inset-inline`, `--_shift-x`, `--_shift-y`, `--_sign-x`, `--_sign-y` and `--_text-color`.
+
+### anchor.css
+
+- `--_shift-x`: Horizontal shift of `.ui-floating`. Defaults to `0`.
+- `--_shift-y`: Vertical shift of `.ui-floating`. Defaults to `0`.
+
+## Theme tokens
+
+The stylesheets read `--ui-accent-fill-max-lightness`, `--ui-border-width-thick`, `--ui-critical`, `--ui-duration`, `--ui-ease-enter`, `--ui-font-size-caption`, `--ui-font-weight-medium`, `--ui-info`, `--ui-motion`, `--ui-neutral`, `--ui-on-fill`, `--ui-on-primary`, `--ui-on-warning`, `--ui-primary`, `--ui-radius-round`, `--ui-space-1`, `--ui-space-2`, `--ui-space-4`, `--ui-success` and `--ui-warning`. `theming.md` and `tokens.json` describe them.
+
+## HTML
+
+### Example: Basics
+
+```html
+<span class="ui-badge">
+  <svg
+    aria-hidden="true"
+    xmlns="http://www.w3.org/2000/svg"
+    width="32"
+    height="32"
+    viewBox="0 0 32 32"
+  >
+    <path
+      fill="currentColor"
+      d="M2.004 9.303A4.5 4.5 0 0 1 6.5 5h19a4.5 4.5 0 0 1 4.496 4.303l-1.476.82L16 16.864L3.48 10.123zM2 11.588V22.5A4.5 4.5 0 0 0 6.5 27h19a4.5 4.5 0 0 0 4.5-4.5V11.588l-.526.293l-13 7a1 1 0 0 1-.948 0L2.514 11.874z"
+    ></path>
+  </svg>
+  <span class="ui-floating">
+    <span class="ui-indicator"
+      ><span aria-hidden="true">5</span
+      ><span class="ui-sr-only">5 unread messages</span></span
+    >
+  </span>
+</span>
+
+<span class="ui-badge ui-dot">
+  <svg aria-hidden="true" viewBox="0 0 32 32"></svg>
+  <span class="ui-floating">
+    <span class="ui-indicator"
+      ><span class="ui-sr-only">New messages</span></span
+    >
+  </span>
+</span>
+```
+
+## Astro
+
+`import { Badge } from "opui-css/astro"`
+
+- `Badge` named slots: `indicator`. Fill one with `slot="indicator"` on a child.
+
+### Example: Basics
+
+```astro
+---
+import { Badge } from "opui-css/astro"
+---
+
+<Badge hideLabel label="5 unread messages">
+  <svg
+    aria-hidden="true"
+    xmlns="http://www.w3.org/2000/svg"
+    width="32"
+    height="32"
+    viewBox="0 0 32 32"
+    ><path
+      fill="currentColor"
+      d="M2.004 9.303A4.5 4.5 0 0 1 6.5 5h19a4.5 4.5 0 0 1 4.496 4.303l-1.476.82L16 16.864L3.48 10.123zM2 11.588V22.5A4.5 4.5 0 0 0 6.5 27h19a4.5 4.5 0 0 0 4.5-4.5V11.588l-.526.293l-13 7a1 1 0 0 1-.948 0L2.514 11.874z"
+    ></path></svg
+  >
+  <Fragment slot="indicator">5</Fragment>
+</Badge>
+
+<Badge dot label="New messages">
+  <svg
+    aria-hidden="true"
+    xmlns="http://www.w3.org/2000/svg"
+    width="32"
+    height="32"
+    viewBox="0 0 32 32"
+    ><path
+      fill="currentColor"
+      d="M2.004 9.303A4.5 4.5 0 0 1 6.5 5h19a4.5 4.5 0 0 1 4.496 4.303l-1.476.82L16 16.864L3.48 10.123zM2 11.588V22.5A4.5 4.5 0 0 0 6.5 27h19a4.5 4.5 0 0 0 4.5-4.5V11.588l-.526.293l-13 7a1 1 0 0 1-.948 0L2.514 11.874z"
+    ></path></svg
+  >
+</Badge>
+```
+
+## React
+
+`import { Badge } from "opui-css/react"`
+
+- `Badge` slot props (`ReactNode`): `children` and `indicator`.
+
+### Example: Basics
+
+```tsx
+import { Badge } from "opui-css/react"
+
+export default function Basics() {
+  return (
+    <>
+      <Badge hideLabel indicator="5" label="5 unread messages">
+        <svg aria-hidden="true" viewBox="0 0 32 32"></svg>
+      </Badge>
+
+      <Badge dot label="New messages">
+        <svg aria-hidden="true" viewBox="0 0 32 32"></svg>
+      </Badge>
+    </>
+  )
+}
+```
+
+## Svelte
+
+`import { Badge } from "opui-css/svelte"`
+
+- `Badge` slot snippets: `children` and `indicator`.
+
+### Example: Basics
+
+```svelte
+<script lang="ts">
+  import { Badge } from "opui-css/svelte"
+</script>
+
+<Badge hideLabel label="5 unread messages">
+  <svg aria-hidden="true" viewBox="0 0 32 32"></svg>
+  {#snippet indicator()}5{/snippet}
+</Badge>
+
+<Badge dot label="New messages">
+  <svg aria-hidden="true" viewBox="0 0 32 32"></svg>
+</Badge>
+```
+
+## Vue
+
+`import { Badge } from "opui-css/vue"`
+
+- `Badge` named slots: `indicator`. Fill one with `<template #indicator>`.
+
+### Example: Basics
+
+```vue
+<script setup lang="ts">
+import { Badge } from "opui-css/vue"
+</script>
+
+<template>
+  <Badge hideLabel label="5 unread messages">
+    <svg aria-hidden="true" viewBox="0 0 32 32"></svg>
+    <template #indicator>5</template>
+  </Badge>
+
+  <Badge dot label="New messages">
+    <svg aria-hidden="true" viewBox="0 0 32 32"></svg>
+  </Badge>
+</template>
+```