opui-css 3.3.5 → 4.0.0

package/components/AGENTS.md

@@ -0,0 +1,247 @@
+# UI Component Implementation Guide
+
+This guide defines the standards for implementing reusable Astro UI components in this package (`packages/opui/components/<Name>/<Name>.astro`) based on the documentation specs at `src/docs/components/`. Use it as a reference for maintaining consistency and accessibility across the library.
+
+**CRITICAL INSTRUCTION**: Always use components from this package (imported via the `@opui/astro` alias) and their corresponding CSS from `packages/opui/css/components/` whenever possible. Avoid writing custom CSS if an existing component or utility can achieve the desired result.
+
+## 0. Implementation Checklist
+
+When implementing or updating a component, ensure:
+- [ ] **Title Export**: `export const title = "Component Name"` is present.
+- [ ] **Props Type**: Used `type Props = { ... }` (avoid interfaces).
+- [ ] **Sorting**: Props, Destructuring, and Classes are sorted alphabetically.
+- [ ] **Rest Props**: `...rest` is captured and spread onto the root element.
+- [ ] **Class Management**: Used `class:list` for all class manipulations.
+- [ ] **ID Stability**: Used `Astro.locals.$id` for any internal element linking.
+- [ ] **Accessibility**: ARIA labels, roles, and relationships are correctly handled.
+- [ ] **Slot Strategy**: Named slots are used for structural content (icons, actions).
+
+---
+
+## 1. Frontmatter Structure
+
+Every component must follow this exact frontmatter layout:
+
+```astro
+---
+type Props = {
+  [key: string]: any // Required for ...rest support
+  class?: string
+  disabled?: boolean
+  label?: string
+  size?: "small" | "large"
+  variant?: "outlined" | "tonal" | "filled"
+}
+
+export const title = "My Component"
+
+const {
+  class: className,
+  disabled,
+  label,
+  size,
+  variant = "outlined", // Default values in destructuring
+  ...rest
+} = Astro.props
+---
+```
+
+### Key Rules:
+- **Alphabetical Sorting**: Sort property definitions in `type Props` and variables in the destructuring statement.
+- **REST Support**: Always include `[key: string]: any` in props and `...rest` in destructuring.
+- **Title Export**: This is mandatory for documentation generation.
+
+---
+
+## 2. Component Composition & Tags
+
+### Dynamic Elements (Polymorphism)
+For components that can be different HTML elements (e.g., `Button` as `<a>` or `<button>`), use a dynamic `Tag` variable.
+
+```astro
+---
+const { as: Tag = Astro.props.href ? "a" : "button", ...rest } = Astro.props
+---
+<Tag {...rest}><slot /></Tag>
+```
+- **Inference**: Default to `"a"` if `href` is present.
+- **Override**: Allow manual override via the `as` prop.
+
+### Styling Inheritance
+Components should often inherit styles from others (e.g., `Dialog` looking like a `Card`). Use conditional classes to apply the inherited base class.
+
+```astro
+<dialog class:list={["dialog", { card: variant }, variant, className]} {...rest}>
+```
+
+---
+
+## 3. Class Management
+
+Use `class:list` exclusively. Follow this order for readability:
+1.  **Component Base Class**: The primary CSS class (e.g., `"button"`).
+2.  **State Objects**: Boolean flags (e.g., `{ active, disabled, error }`).
+3.  **Variant Props**: Direct string values from props (e.g., `size`, `variant`).
+4.  **External Class**: Always include `className` at the end to allow for overrides.
+
+```astro
+<div
+  class:list={[
+    "chip",
+    {
+      multiline: isMultiline,
+      selected,
+    },
+    size,
+    variant,
+    className,
+  ]}
+>
+```
+
+---
+
+## 4. Slot Patterns
+
+### Default Slots vs Label Props
+For simple text-based components, provide both a `label` prop and a default slot.
+
+```astro
+<div class="component">
+  { (label || Astro.slots.has("default")) && (
+    <span class="text">
+      {label}
+      <slot />
+    </span>
+  )}
+</div>
+```
+
+### Named Slots (Icons & Actions)
+Use named slots for specific functional areas. Check for existence before rendering wrapper tags.
+
+```astro
+<div class="card">
+  {Astro.slots.has("header") && <header><slot name="header" /></header>}
+  <slot />
+  {Astro.slots.has("actions") && <footer class="actions"><slot name="actions" /></footer>}
+</div>
+```
+
+---
+
+## 5. Form & Input Patterns
+
+### Label Wrapping
+Most inputs should be wrapped in a `<label>` to provide a larger hit area and built-in accessibility.
+
+```astro
+<label class:list={["field", { disabled, error }]}>
+  <span class="label">{label}</span>
+  <input type="text" {...rest} />
+  {endText && <span class="end-text">{endText}</span>}
+</label>
+```
+
+### End Text & ARIA
+When providing `endText`, use `Astro.locals.$id` to link it to the input via `aria-describedby`.
+
+```astro
+---
+const { $id } = Astro.locals
+const helpId = $id("help")
+---
+<input aria-describedby={endText ? helpId : undefined} />
+{endText && <span id={helpId}>{endText}</span>}
+```
+
+### Input Attribute Mapping
+Explicitly define and pass through native input attributes in the `Props` type for better IDE support.
+
+```astro
+<input
+  disabled={disabled}
+  name={name}
+  required={required}
+  type={type}
+  value={value}
+  {...rest}
+/>
+```
+
+### Sub-component Decomposition
+For complex inputs (like `Checkbox` with custom visuals), split the component into a public wrapper (`Checkbox.astro`) and a private raw input (`CheckboxInput.astro`) to keep the root element clean.
+
+### Form Structure: FieldSet, FieldLegend, FieldDescription, FieldGroup
+When building forms, follow this nesting order inside a `FieldSet`:
+1. `FieldLegend` - The heading/label for the fieldset
+2. `FieldDescription` - Optional helper text
+3. `FieldGroup` - Wrapper for the actual form controls
+
+**Always wrap form elements in a `FieldGroup`**, never place them directly after `FieldLegend` or `FieldDescription`.
+
+```astro
+<!-- ✅ Correct -->
+<FieldSet>
+  <FieldLegend>Username</FieldLegend>
+  <FieldDescription>Enter your preferred username.</FieldDescription>
+  <FieldGroup>
+    <TextField placeholder="e.g. jdoe" />
+  </FieldGroup>
+</FieldSet>
+
+<!-- ❌ Incorrect - TextField directly after FieldDescription -->
+<FieldSet>
+  <FieldLegend>Username</FieldLegend>
+  <FieldDescription>Enter your preferred username.</FieldDescription>
+  <TextField placeholder="e.g. jdoe" />
+</FieldSet>
+```
+
+---
+
+## 6. Identification & Accessibility
+
+### Unique IDs
+Always use `Astro.locals.$id` for IDs. This ensures stability across server and client rendering and prevents ID collisions when multiple instances of the same component are on a page.
+
+```astro
+const { $id } = Astro.locals
+const fieldId = id || $id("input") // Prefer passed ID if available
+```
+
+### Default Icons
+Components like `Callout` or `Toast` should provide default SVG icons within their named slots, while allowing users to override them.
+
+```astro
+<slot name="icon">
+  {severity === "error" && <svg>...</svg>}
+</slot>
+```
+
+---
+
+## 7. Data-Driven Components
+
+For repetitive structures (DescriptionLists, Menus, Selects), prefer an `items` prop alongside standard slots.
+
+```astro
+type Item = { label: string; value: any }
+type Props = { items?: Item[] }
+
+<ul>
+  {items.map(item => <li>{item.label}</li>)}
+  <slot /> <!-- Still allow manual entries -->
+</ul>
+```
+
+---
+
+## 8. Development Workflow
+
+1.  **Read the Spec**: Open `src/docs/components/[name].astro` to see required HTML and CSS classes. (Component docs live under `src/docs/components/` now; `src/pages/components/` only contains route shells.)
+2.  **Analyze the API**: Check `src/component-api/[name]/` (`Astro.astro` and `HTML.astro`) or `src/component-api/[name]-api.astro` for the documented props.
+3.  **Implement**: Follow the checklist in Section 0.
+4.  **Verify**: Check that your implementation matches the "HTML" preview in the rendered `Example` for the spec page (`/components/[name]`). For framework-specific behaviour, also verify the Astro variant at `/astro/components/[name]`.
+
+

package/components/Accordion/Accordion.astro

@@ -0,0 +1,42 @@
+---
+type Props = {
+  class?: string
+  name?: string
+  open?: boolean
+  variant?: "default" | "outlined" | "elevated" | "tonal"
+  [key: string]: any
+}
+
+export const title = "Accordion"
+
+const { $id } = Astro.locals
+const { class: className, name, open, variant, ...rest } = Astro.props
+
+const summaryId = $id("summary")
+const contentId = $id("content")
+---
+
+<details
+  name={name}
+  class:list={["accordion", "card", variant, className]}
+  open={open}
+  {...rest}
+>
+  <!-- Summary -->
+  <!-- prettier-ignore -->
+  <summary id={summaryId} aria-controls={contentId}><slot name="summary" /><slot name="marker" /></summary>
+
+  <!-- Content -->
+  <div id={contentId} class="content" role="region" aria-labelledby={summaryId}>
+    <slot />
+  </div>
+
+  <!-- Actions -->
+  {
+    Astro.slots.has("actions") && (
+      <div class="actions">
+        <slot name="actions" />
+      </div>
+    )
+  }
+</details>

package/components/Anchor/Anchor.astro

@@ -0,0 +1,51 @@
+---
+type Props = {
+  [key: string]: any
+  alignment?: string
+  class?: string
+  id?: string
+  trigger?: "always" | "hover"
+}
+
+export const title = "Anchor"
+
+const {
+  alignment,
+  class: className,
+  id: idProp,
+  trigger = "always",
+  ...rest
+} = Astro.props
+
+const isHover = trigger === "hover"
+const id = isHover ? (idProp ?? Astro.locals.$id("anchor")) : undefined
+
+const insetMap: Record<string, string> = {
+  "start start": "auto 100% 100% auto",
+  "start end": "auto auto 100% 100%",
+  "end start": "100% 100% auto auto",
+  "end end": "100% auto auto 100%",
+}
+
+const positionArea = alignment
+  ? {
+      "--anchor-position-area": alignment,
+      "--_anchor-inset": insetMap[alignment],
+    }
+  : {}
+---
+
+<span class:list={["anchor", className]} style={positionArea} {...rest}>
+  {
+    isHover ? (
+      <span {...({ interestfor: id } as any)}>
+        <slot />
+      </span>
+    ) : (
+      <slot />
+    )
+  }
+  <span class="anchor-floating" id={id} popover={isHover ? "hint" : undefined}>
+    <slot name="anchored" />
+  </span>
+</span>

package/components/Avatar/Avatar.astro

@@ -0,0 +1,44 @@
+---
+type Props = {
+  [key: string]: any
+  alt?: string
+  as?: "div" | "a" | "button" | string
+  class?: string
+  href?: string
+  isGroup?: boolean
+  spacing?: "small" | "x-small"
+  src?: string
+  variant?: "squared" | "rounded" | "squircle"
+}
+
+export const title = "Avatar"
+
+const {
+  alt,
+  as,
+  class: className,
+  href,
+  isGroup,
+  spacing,
+  src,
+  variant,
+  ...rest
+} = Astro.props
+
+const Tag = as || (href ? "a" : "div")
+---
+
+<!-- prettier-ignore -->
+<Tag
+  class:list={[
+    { avatar: !isGroup },
+    !isGroup && variant,
+    {
+      "gap-small": isGroup && spacing === "small",
+      "gap-x-small": isGroup && spacing === "x-small",
+    },
+    className,
+  ]}
+  href={href}
+  role={isGroup ? "group" : undefined}
+  {...rest}>{src ? <img src={src} alt={alt} /> : <slot />}</Tag>

package/components/Badge/Badge.astro

@@ -0,0 +1,54 @@
+---
+import Anchor from "../Anchor/Anchor.astro"
+
+type Props = {
+  [key: string]: any
+  alignment?: "start-start" | "end-start" | "end-end"
+  class?: string
+  color?: "critical" | "info" | "neutral" | "success" | "warning"
+  dot?: boolean
+  invisible?: boolean
+  label?: string | number
+}
+
+export const title = "Badge"
+
+const {
+  alignment,
+  class: className,
+  color,
+  dot,
+  invisible,
+  label,
+  ...rest
+} = Astro.props
+
+const positionArea =
+  alignment === "start-start"
+    ? "start start"
+    : alignment === "end-start"
+      ? "end start"
+      : alignment === "end-end"
+        ? "end end"
+        : undefined
+---
+
+<Anchor
+  alignment={positionArea}
+  class:list={[
+    "badge",
+    {
+      dot,
+      invisible,
+    },
+    alignment,
+    className,
+    color,
+  ]}
+  {...rest}
+>
+  <slot />
+  <span class="badge-indicator" slot="anchored" aria-label={label?.toString()}
+    >{dot ? "" : label}</span
+  >
+</Anchor>

package/components/Button/Button.astro

@@ -0,0 +1,45 @@
+---
+type CommonProps = {
+  [key: string]: any
+  as?: string
+  class?: string
+  color?: "critical" | "primary"
+  size?: "x-small" | "small" | "large"
+  variant?: "outlined" | "tonal" | "filled"
+}
+
+type AnchorProps = CommonProps & {
+  disabled?: never
+  href: string
+}
+
+type ButtonProps = CommonProps & {
+  disabled?: boolean
+  href?: undefined
+}
+
+type Props = AnchorProps | ButtonProps
+
+export const title = "Button"
+
+const {
+  as,
+  class: className,
+  color,
+  disabled,
+  href,
+  size,
+  variant,
+  ...rest
+} = Astro.props
+
+const Tag = as || (href ? "a" : "button")
+const isButton = Tag === "button"
+---
+
+<!-- prettier-ignore -->
+<Tag
+  class:list={["button", { disabled: isButton && disabled }, size, variant, color, className]}
+  disabled={isButton ? disabled : undefined}
+  href={href}
+  {...rest}><slot /></Tag>

package/components/ButtonGroup/ButtonGroup.astro

@@ -0,0 +1,29 @@
+---
+type Props = {
+  [key: string]: any
+  class?: string
+  color?: "critical" | "primary"
+  orientation?: "vertical"
+  size?: "small" | "large"
+  variant?: "outlined" | "tonal" | "filled"
+}
+
+export const title = "Button Group"
+
+const {
+  class: className,
+  color,
+  orientation,
+  size,
+  variant,
+  ...rest
+} = Astro.props
+---
+
+<div
+  class:list={["button-group", color, size, variant, orientation, className]}
+  role="group"
+  {...rest}
+>
+  <slot />
+</div>

package/components/Callout/Callout.astro

@@ -0,0 +1,75 @@
+---
+type Props = {
+  [key: string]: any
+  class?: string
+  severity?: "critical" | "info" | "neutral" | "success" | "warning"
+  variant?: "tonal" | "outlined"
+}
+
+export const title = "Callout"
+
+const { class: className, severity, variant, ...rest } = Astro.props
+---
+
+<article
+  role="note"
+  class:list={["callout", variant, severity, className]}
+  {...rest}
+>
+  <slot name="icon">
+    {
+      severity === "info" && (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="32"
+          height="32"
+          viewBox="0 0 32 32"
+        >
+          <path
+            fill="currentColor"
+            d="M16 13a1 1 0 0 1 1 1v9a1 1 0 1 1-2 0v-9a1 1 0 0 1 1-1m0-2a1.5 1.5 0 1 0 0-3a1.5 1.5 0 0 0 0 3M2 16C2 8.268 8.268 2 16 2s14 6.268 14 14s-6.268 14-14 14S2 23.732 2 16M16 4C9.373 4 4 9.373 4 16s5.373 12 12 12s12-5.373 12-12S22.627 4 16 4"
+          />
+        </svg>
+      )
+    }
+    {
+      severity === "warning" && (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="32"
+          height="32"
+          viewBox="0 0 32 32"
+        >
+          <path
+            fill="currentColor"
+            d="M17.25 22a1.25 1.25 0 1 1-2.5 0a1.25 1.25 0 0 1 2.5 0M16 9a1 1 0 0 0-1 1v8a1 1 0 1 0 2 0v-8a1 1 0 0 0-1-1m-3.064-5.191c1.332-2.41 4.796-2.41 6.128 0l10.493 18.999C30.846 25.14 29.158 28 26.494 28H5.507c-2.665 0-4.352-2.86-3.064-5.192zm4.377.967a1.5 1.5 0 0 0-2.626 0L4.194 23.775A1.5 1.5 0 0 0 5.507 26h20.987a1.5 1.5 0 0 0 1.313-2.225z"
+          />
+        </svg>
+      )
+    }
+    {
+      severity === "critical" && (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="32"
+          height="32"
+          viewBox="0 0 48 48"
+        >
+          <path
+            fill="currentColor"
+            d="M24 13c.69 0 1.25.56 1.25 1.25v12.5a1.25 1.25 0 1 1-2.5 0v-12.5c0-.69.56-1.25 1.25-1.25m0 21a2 2 0 1 0 0-4a2 2 0 0 0 0 4M4 24C4 12.954 12.954 4 24 4s20 8.954 20 20s-8.954 20-20 20S4 35.046 4 24M24 6.5C14.335 6.5 6.5 14.335 6.5 24S14.335 41.5 24 41.5S41.5 33.665 41.5 24S33.665 6.5 24 6.5"
+          />
+        </svg>
+      )
+    }
+  </slot>
+  <div class="content">
+    {
+      Astro.slots.has("title") && (
+        <!-- prettier-ignore -->
+        <h3 class="title"><slot name="title" /></h3>
+      )
+    }
+    <slot />
+  </div>
+</article>

package/components/Card/Card.astro

@@ -0,0 +1,38 @@
+---
+type Props = {
+  variant?: "text" | "outlined" | "elevated" | "tonal"
+  actions?: {
+    align?: "end"
+  }
+  [key: string]: any
+}
+
+export const title = "Card"
+
+const { variant, actions, class: className, ...rest } = Astro.props
+---
+
+<div class:list={["card", variant, className]} {...rest}>
+  {
+    Astro.slots.has("header") && (
+      <hgroup>
+        <slot name="header" />
+      </hgroup>
+    )
+  }
+  {
+    Astro.slots.has("content") && (
+      <div class="content">
+        <slot name="content" />
+      </div>
+    )
+  }
+  <slot />
+  {
+    Astro.slots.has("actions") && (
+      <div class:list={["actions", actions?.align && `align-${actions.align}`]}>
+        <slot name="actions" />
+      </div>
+    )
+  }
+</div>

package/components/Checkbox/Checkbox.astro

@@ -0,0 +1,76 @@
+---
+import CheckboxInput from "./CheckboxInput.astro"
+
+type Props = {
+  [key: string]: any
+  checked?: boolean
+  class?: string
+  critical?: boolean
+  disabled?: boolean
+  hideLabel?: boolean
+  id?: string
+  indeterminate?: boolean
+  name?: string
+  required?: boolean
+  size?: "small" | "large"
+  spread?: boolean
+  stack?: boolean
+  value?: string
+}
+
+export const title = "Checkbox"
+
+const {
+  checked,
+  class: className,
+  critical,
+  disabled,
+  hideLabel,
+  id,
+  indeterminate,
+  name,
+  required,
+  size,
+  spread,
+  stack,
+  value,
+  ...rest
+} = Astro.props
+
+const { $id, currentFieldName } = Astro.locals
+const endTextId = Astro.slots.has("end-text") ? $id("end-text") : undefined
+
+const finalName = name || currentFieldName
+---
+
+<label
+  class:list={[
+    "checkbox",
+    size,
+    {
+      stack,
+      spread,
+    },
+    className,
+  ]}
+  data-invalid={critical || undefined}
+>
+  <CheckboxInput
+    aria-describedby={endTextId}
+    {checked}
+    {disabled}
+    {id}
+    {indeterminate}
+    name={finalName}
+    {required}
+    {value}
+    {...rest}
+  />
+  <!-- prettier-ignore --><span class:list={[hideLabel ? "sr-only" : "label"]}><slot /></span>
+  {
+    Astro.slots.has("end-text") && (
+      <!-- prettier-ignore -->
+      <span id={endTextId} class="end-text"><slot name="end-text" /></span>
+    )
+  }
+</label>