@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/docs/src/core/components/ui/toast/toast.md

@@ -0,0 +1,216 @@
+# Toast
+
+Toasts surface **short-lived feedback** in a fixed stack (bottom-right in the main window). Queue messages with **`SonicToast.add()`** on the global **`SonicToast`** class—the host **`sonic-toast`** is created automatically. Prefer **`label`** for a heading; use **`preserve`** or interactive **`text`** when the user must read or act before dismiss.
+
+## Basic example
+
+Click the button to show a toast.
+
+<sonic-code>
+  <template>
+    <sonic-button onclick="SonicToast.add({ text: 'Simple notification' })">
+      Show toast
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Status
+
+**`status`** drives color, icon, and live-region behavior. Omit **`status`** or pass an empty string for a neutral toast.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button onclick="SonicToast.add({ text: 'Default message', status: '' })">
+        Default
+      </sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Operation succeeded', status: 'success' })">
+        Success
+      </sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Something went wrong', status: 'error' })">
+        Error
+      </sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Check this detail', status: 'warning' })">
+        Warning
+      </sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Helpful context', status: 'info' })">
+        Info
+      </sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Label
+
+Set **`label`** for a bold title above **`text`**. **`title`** still works but is deprecated—use **`label`** in new code.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button
+        onclick="SonicToast.add({ label: 'Success', text: 'Your request was processed.', status: 'success' })"
+      >
+        Toast with label
+      </sonic-button>
+      <sonic-button
+        onclick="SonicToast.add({ label: 'Error', text: 'Processing failed. Try again.', status: 'error' })"
+      >
+        Error with label
+      </sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## HTML in text
+
+**`text`** (and **`label`**) can include HTML strings. Links and controls in **`text`** automatically enable **`preserve`** so the toast does not auto-hide while the user interacts.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Message with <strong>HTML</strong> and an <a href=&quot;#&quot;>action link</a>', status: 'info' })"
+    >
+      Toast with HTML
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Preserve
+
+Without **`preserve`**, toasts auto-hide after about six seconds (timer pauses on hover or focus). Set **`preserve`** to keep the toast until the user closes it.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({ text: 'This toast stays until you dismiss it', status: 'info', preserve: true })"
+    >
+      Persistent toast
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Dismiss forever
+
+With **`dismissForever`** and a stable **`id`**, closing the toast stores dismissal in **`localStorage`**—**`SonicToast.add`** skips it on later visits. Duplicate payloads (same fields, ignoring **`id`**) are not queued twice.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({ id: 'unique-toast-id', text: 'Dismiss forever hides this across reloads', status: 'info', dismissForever: true })"
+    >
+      Dismiss forever
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Ghost
+
+**`ghost`** renders a semi-transparent, non-interactive toast—useful for loading or background states. **`SonicToast.removeAll`** leaves ghost toasts in place.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Ghost toast (non-interactive)', status: 'info', ghost: true })"
+    >
+      Ghost toast
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Dismissal
+
+Use static helpers to clear the stack from app logic (for example after navigation).
+
+### Remove all
+
+Removes every toast except **`ghost`** items.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button onclick="SonicToast.add({ text: 'Toast 1', status: 'info' })">Add toast 1</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Toast 2', status: 'success' })">Add toast 2</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Toast 3', status: 'warning' })">Add toast 3</sonic-button>
+      <sonic-button onclick="SonicToast.removeAll()">Remove all</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+### Remove by status
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button onclick="SonicToast.add({ text: 'Success toast', status: 'success' })">Success</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Error toast', status: 'error' })">Error</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Warning toast', status: 'warning' })">Warning</sonic-button>
+      <sonic-button onclick="SonicToast.removeItemsByStatus('success')">Remove success</sonic-button>
+      <sonic-button onclick="SonicToast.removeItemsByStatus('error')">Remove error</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+### Remove temporary items
+
+Removes toasts that are not **`preserve`**.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button onclick="SonicToast.add({ text: 'Temporary toast', status: 'info' })">Temporary</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Persistent toast', status: 'success', preserve: true })">
+        Persistent
+      </sonic-button>
+      <sonic-button onclick="SonicToast.removeTemporaryItems()">Remove temporary</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Combined options
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({
+      id: 'welcome-toast',
+      label: 'Welcome',
+      text: 'Welcome to the platform. Explore the docs to get started.',
+      status: 'success',
+      dismissForever: true
+    })"
+    >
+      Full example
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Accessibility
+
+Each toast uses **`role="alert"`** for **`error`** and **`role="status"`** otherwise (with **`aria-live="polite"`** when applicable). Status icons are decorative (**`aria-hidden`**). The close control has an i18n **`aria-label`**. When there is no **`label`**, a truncated string **`aria-label`** may be derived from plain **`text`**.
+
+## API reference
+
+Options passed to **`SonicToast.add(conf)`**:
+
+| Option | Values | Description |
+|----------|---------|-------------|
+| `text` | string · Lit template | Main body; HTML strings are supported |
+| `label` | string · Lit template | Optional heading above **`text`** |
+| `title` | string · Lit template | Deprecated alias for **`label`** |
+| `status` | `success` · `error` · `warning` · `info` · `` (empty) | Semantic styling and live region behavior |
+| `id` | string · number | Stable id for deduplication and **`dismissForever`** (defaults to timestamp) |
+| `preserve` | boolean | Skip auto-hide; forced when **`text`** contains interactive markup |
+| `ghost` | boolean | Semi-transparent and non-interactive; kept by **`removeAll`** |
+| `dismissForever` | boolean | Persist dismissal in **`localStorage`** when closed (requires stable **`id`**) |
+| `styleSheet` | modal style input | Extra adopted styles on the toast item shadow root |
+| `useSlot` | boolean | Legacy: project **`text`** into the light DOM slot |
+
+| Method | Description |
+|--------|-------------|
+| `SonicToast.add(conf)` | Append a toast; returns the config or **`null`** if skipped (dismissed forever or duplicate) |
+| `SonicToast.removeAll()` | Remove all non-**`ghost`** toasts |
+| `SonicToast.removeItemsByStatus(status)` | Remove toasts matching **`status`** |
+| `SonicToast.removeItemById(id)` | Remove a single toast by **`id`** |
+| `SonicToast.removeTemporaryItems()` | Remove toasts without **`preserve`** |
+
+**`sonic-toast`** is mounted automatically; **`sonic-toast-item`** is internal. In iframes, toasts can delegate to the parent window via **`postMessage`**.

package/docs/src/core/components/ui/tooltip/tooltip.md

@@ -0,0 +1,124 @@
+# Tooltip
+
+Tooltip shows a short **`label`** on hover (and on focus when the trigger can receive focus). Wrap the trigger in the default slot—buttons, icons, or plain text. Default **`placement`** is **`top`** (center-aligned). An empty **`label`** hides the bubble the same way as **`disabled`**.
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-tooltip label="Additional context on hover">
+      <sonic-button variant="outline">Hover me</sonic-button>
+    </sonic-tooltip>
+  </template>
+</sonic-code>
+
+## Placement
+
+Use **`top`** · **`bottom`** · **`left`** · **`right`** for the main axis. Add **`-start`** or **`-end`** to align the bubble along the anchor edge.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-tooltip placement="top" label="Top">
+        <sonic-button>Top</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="bottom" label="Bottom">
+        <sonic-button>Bottom</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="right" label="Right">
+        <sonic-button>Right</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="left" label="Left">
+        <sonic-button>Left</sonic-button>
+      </sonic-tooltip>
+    </div>
+  </template>
+</sonic-code>
+
+### Aligned placements
+
+<sonic-code>
+  <template>
+    <div class="flex gap-3 flex-wrap">
+      <sonic-tooltip placement="top-start" label="Top start">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Top start</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="top-end" label="Top end">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Top end</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="bottom-start" label="Bottom start">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Bottom start</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="bottom-end" label="Bottom end">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Bottom end</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="right-start" label="Right start">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Right start</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="right-end" label="Right end">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Right end</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="left-start" label="Left start">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Left start</sonic-button>
+      </sonic-tooltip>
+      <sonic-tooltip placement="left-end" label="Left end">
+        <sonic-button class="size-40 bg-neutral-200 rounded-lg">Left end</sonic-button>
+      </sonic-tooltip>
+    </div>
+  </template>
+</sonic-code>
+
+## Label formatting
+
+**`label`** supports line breaks (`\n` in markup or multiline text). Lines are trimmed; **`&nbsp;`** is normalized to spaces. **`white-space: pre-line`** preserves breaks in the bubble (max width **18rem**).
+
+<sonic-code>
+  <template>
+    <sonic-tooltip label="First line&#10;Second line">
+      <sonic-button variant="outline">Multiline label</sonic-button>
+    </sonic-tooltip>
+  </template>
+</sonic-code>
+
+## Focusable
+
+On non-interactive triggers, set **`focusable`** so the host gets **`tabindex="0"`** and the tooltip opens on keyboard focus as well as hover.
+
+<sonic-code>
+  <template>
+    <sonic-tooltip
+      focusable
+      label="The Concorde made its first transatlantic crossing on September 26, 1973"
+    >
+      <sonic-icon library="iconoir" name="chat-bubble-question"></sonic-icon>
+      Focus or hover this text
+    </sonic-tooltip>
+  </template>
+</sonic-code>
+
+## Disabled
+
+<sonic-code>
+  <template>
+    <sonic-tooltip disabled label="Not shown">
+      <sonic-button>Tooltip disabled</sonic-button>
+    </sonic-tooltip>
+  </template>
+</sonic-code>
+
+## Accessibility
+
+The bubble uses **`popover="hint"`** (non-modal, no pointer capture). Prefer **`focusable`** when the slotted content is not already focusable. When the Popover API is unavailable, the host falls back to the native **`title`** attribute with a single-line label. Opacity transitions respect **`prefers-reduced-motion`**.
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `label` | string | Tooltip copy; whitespace-only values suppress the bubble |
+| `placement` | `top` (default) · `bottom` · `left` · `right` · `top-start` · `top-end` · `bottom-start` · `bottom-end` · `left-start` · `left-end` · `right-start` · `right-end` | Position relative to the trigger; repositions while open |
+| `disabled` | boolean | Suppress show/hide; sets **`tabindex="-1"`** on the host |
+| `focusable` | boolean | Add **`tabindex="0"`** on the host for keyboard access |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Trigger content (hover target) |

package/docs/src/docs/_getting-started/theming.md

@@ -0,0 +1,253 @@
+# Customization
+
+## Theme-first customization
+
+Concorde components ship with **default styles** (fallback values in each component and in `<sonic-theme>`).  
+You do not need to define any CSS variables to get a usable UI.
+
+To align the kit with your brand, override **only the essential theme tokens** on `<sonic-theme>`, on `:root`, or in a project stylesheet.  
+Concorde derives radius steps, button/input rounding, shadows, and most per-component layout from these primitives—**do not copy long lists of derived variables** unless you have a specific need.
+
+<sonic-code language="html">
+  <template>
+<sonic-theme color font class="block bg-base min-h-screen">
+  <!-- your app -->
+</sonic-theme>
+  </template>
+</sonic-code>
+
+<sonic-code language="javascript">
+  <template>
+import "@supersoniks/concorde/theme";
+  </template>
+</sonic-code>
+
+| Attribute | Effect |
+|-----------|--------|
+| *(omit)* \| `theme="custom"` | Default: core tokens + your `--sc-*`; no built-in light/dark palette |
+| `theme="light"` \| `"dark"` \| `"auto"` | Opt-in presets; `auto` follows `prefers-color-scheme` |
+| `class="bg-base block"` (Tailwind) | Page/surface background (`--sc-base`) |
+| `color` | Text color (`--sc-base-content`) |
+| `font` | Base font family/weight (`--sc-font-family-base`, etc.) |
+
+Popovers, modals, and toasts mount under the nearest `<sonic-theme>`.
+
+## Customization example
+
+Example (full brand override on `<sonic-theme>` or `:root`). Set every essential token below; derived radii and shadows still come from the theme engine—only `--sc-rounded` is listed here.
+
+<sonic-code language="css">
+  <template>
+sonic-theme {
+  /* Semantic fills */
+  --sc-primary: #353429;
+  --sc-secondary: #f43f5e;
+  --sc-info: #7c3aed;
+  --sc-danger: #d71839;
+  --sc-warning: #f97316;
+  --sc-success: #10b981;
+  --sc-contrast: #111;
+
+  /* Text/icons on semantic fills */
+  --sc-primary-content: #fff;
+  --sc-secondary-content: #fff;
+  --sc-info-content: #fff;
+  --sc-danger-content: #fff;
+  --sc-warning-content: #fff;
+  --sc-success-content: #fff;
+  --sc-contrast-content: #fff;
+
+  /* Neutral fills */
+  --sc-base: #fff;
+  --sc-base-50: #f6f6f5;
+  --sc-base-100: #ededec;
+  --sc-base-200: #d7d7d4;
+  --sc-base-300: #c8c7c4;
+  --sc-base-400: #a8a7a2;
+  --sc-base-500: #94938c;
+  --sc-base-600: #76756c;
+  --sc-base-700: #59584e;
+  --sc-base-800: #47463b;
+  --sc-base-900: #353429;
+
+  /* Text/icons on neutral surfaces */
+  --sc-base-content: var(--sc-base-900);
+
+  /* Typography */
+  --sc-font-family-base: "Oswald", system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  --sc-headings-font-family: "alternate-gothic-compressed", system-ui, sans-serif;
+  --sc-headings-line-height: 1.1;
+  --sc-headings-font-weight: bold;
+  --sc-headings-text-transform: none;
+
+  /* Shape (primitive only) */
+  --sc-rounded: 0;
+
+  /* Forms */
+  --sc-border-width: 0.2rem;
+  --sc-form-height: 2em;
+  --sc-input-bg: var(--sc-base);
+  --sc-input-color: var(--sc-base-content);
+  --sc-input-border-color: var(--sc-input-color);
+  --sc-input-active-bg: var(--sc-primary);
+  --sc-input-active-color: var(--sc-primary-content);
+  --sc-input-active-border-color: var(--sc-primary);
+}
+  </template>
+</sonic-code>
+
+<sonic-button href="https://delanfranchi.github.io/concordecolors/"> Palette generator: concordecolors</sonic-button>
+
+
+**Without these overrides**, components keep Concorde’s per-component fallbacks. Built-in light/dark palettes apply only when you set `theme="light"`, `theme="dark"`, or `theme="auto"`.
+
+**What we intentionally avoid:** large public `--sc-alert-*` / `--sc-badge-*` APIs or `::part()` styling hooks on most components. Prefer attributes (`type`, `status`, `size`, …) and the theme tokens above.
+
+
+## Only essential CSS variables (public theme API)
+
+These are the **smallest set** we recommend customizing. Everything else should stay internal to the theme or to components (`--sc_*` private variables, attributes like `type`, `size`, `variant`).
+
+### Surfaces and foreground
+
+Tokens **without** a `-content` suffix are **fill / background** colors.  
+Tokens **with** `-content` are **text and icons** on top of the matching fill (solid buttons, badges, alerts, etc.).
+
+#### Neutral fills
+
+| Variable | Role |
+|----------|------|
+| `--sc-base` | Main surface / page background |
+| `--sc-base-50` … `--sc-base-900` | Neutral scale (borders, subtle backgrounds, muted UI) |
+
+#### Neutral foreground
+
+| Variable | Role |
+|----------|------|
+| `--sc-base-content` | Default body text and icons on neutral surfaces |
+
+#### Semantic fills
+
+| Variable | Role |
+|----------|------|
+| `--sc-primary` | Primary actions, links, emphasis |
+| `--sc-secondary` | Secondary brand accent (when used) |
+| `--sc-info`, `--sc-success`, `--sc-warning`, `--sc-danger` | Status and feedback |
+| `--sc-contrast` | High-contrast fills (e.g. on media) |
+
+#### Semantic foreground
+
+| Variable | Role |
+|----------|------|
+| `--sc-primary-content`, `--sc-secondary-content`, … | Text/icons on the matching semantic **fill** (`--sc-primary`, etc.) |
+
+### Shape
+
+| Variable | Role |
+|----------|------|
+| `--sc-rounded` | **Single primitive** corner radius; the theme computes `--sc-rounded-sm`, `--sc-btn-rounded`, `--sc-input-rounded`, etc. |
+
+### Typography
+
+| Variable | Role |
+|----------|------|
+| `--sc-font-family-base` | Body UI text |
+| `--sc-font-weight-base`, `--sc-font-style-base` | Optional |
+| `--sc-headings-font-family`, `--sc-headings-line-height`, `--sc-headings-font-weight`, `--sc-headings-text-transform` | Headings (modal titles, etc.) |
+
+### Forms (only if you customize inputs globally)
+
+Interactive controls expose a few extra **theme-level** tokens; prefer these over styling individual inputs from outside.
+
+| Variable | Role |
+|----------|------|
+| `--sc-border-width` | Default border thickness |
+| `--sc-form-height` | Control height |
+| `--sc-input-bg`, `--sc-input-color`, `--sc-input-border-color` | Default field chrome |
+| `--sc-input-active-bg`, `--sc-input-active-color`, `--sc-input-active-border-color` | Focus/active state |
+
+---
+
+## Tailwind in new components ?
+
+Set <code>tailwind.config.js</code> to match concorde style token in your custom component.
+
+<sonic-code language="js">
+  <template>
+...
+theme: {
+  borderRadius: {
+    DEFAULT: "var(--sc-rounded)",
+    none: "0",
+    sm: "var(--sc-rounded-sm)",
+    md: "var(--sc-rounded-md)",
+    lg: "var(--sc-rounded-lg)",
+    xl: "var(--sc-rounded-xl)",
+    full: "9999px",
+  },
+  boxShadow: {
+    DEFAULT: "var(--sc-shadow)",
+    none: "none",
+    sm: "var(--sc-shadow-sm)",
+    md: "var(--sc-shadow-md)",
+    lg: "var(--sc-shadow-lg)",
+    xl: "var(--sc-shadow-xl)",
+  },
+  colors: {
+    transparent: "transparent",
+    current: "currentColor",
+    content: "var(--sc-base-content)",
+    base: "var(--sc-base)",
+    neutral: {
+      0: "var(--sc-base)",
+      50: "var(--sc-base-50)",
+      100: "var(--sc-base-100)",
+      200: "var(--sc-base-200)",
+      300: "var(--sc-base-300)",
+      400: "var(--sc-base-400)",
+      500: "var(--sc-base-500)",
+      600: "var(--sc-base-600)",
+      700: "var(--sc-base-700)",
+      800: "var(--sc-base-800)",
+      900: "var(--sc-base-900)",
+      content: "var(--sc-base)",
+    },
+    primary: {
+      DEFAULT: "var(--sc-primary)",
+      content: "var(--sc-primary-content)",
+    },
+    success: {
+      DEFAULT: "var(--sc-success)",
+      content: "var(--sc-success-content)",
+    },
+    danger: {
+      DEFAULT: "var(--sc-danger)",
+      content: "var(--sc-danger-content)",
+    },
+    warning: {
+      DEFAULT: "var(--sc-warning)",
+      content: "var(--sc-warning-content)",
+    },
+    info: {
+      DEFAULT: "var(--sc-info)",
+      content: "var(--sc-info-content)",
+    },
+    contrast: {
+      DEFAULT: "var(--sc-contrast)",
+      content: "var(--sc-contrast-content)",
+    },
+  },
+  extend: {
+    borderWidth: {
+      DEFAULT: "var(--sc-border-width)",
+    },
+    fontFamily: {
+      headings: ["var(--sc-headings-font-family, var(--sc-font-family-base, sans-serif))"],
+      body: ["var(--sc-font-family-base)"],
+      monospace: ["var(--sc-font-family-monospace, monospace)"],
+    }
+  }
+  </template>
+</sonic-code>
+