@lostgradient/cinder 0.5.0 → 0.6.0

package/src/components/floating-action-button/floating-action-button.types.ts

@@ -1,100 +0,0 @@
-import type { Snippet } from 'svelte';
-import type { HTMLAnchorAttributes, HTMLButtonAttributes } from 'svelte/elements';
-
-/**
- * Visual palette of the FAB.
- *
- * - `primary` — uses the primary accent color (solid fill, contrast foreground).
- * - `secondary` — uses the surface-raised background with standard text color.
- * - `surface` — uses the neutral surface color, suited for floating over content.
- *
- * @default `"primary"`
- */
-export type FloatingActionButtonVariant = 'primary' | 'secondary' | 'surface';
-
-/**
- * Size of the FAB. Controls the diameter (`filled`) or height (`extended`).
- *
- * @default `"md"`
- */
-export type FloatingActionButtonSize = 'sm' | 'md' | 'lg';
-
-/**
- * Shape of the FAB.
- *
- * `filled` renders a circle with equal width and height — the classic FAB shape.
- * `extended` renders a pill with auto-width that accommodates icon + label side by side.
- *
- * @default `"filled"`
- */
-export type FloatingActionButtonShape = 'filled' | 'extended';
-
-type SharedBase = {
-  /** Shape. `filled` = circle, `extended` = pill with icon + label. */
-  shape?: FloatingActionButtonShape;
-  /** Size — controls diameter for filled, height for extended. */
-  size?: FloatingActionButtonSize;
-  /** Color palette (primary, secondary, or surface). */
-  variant?: FloatingActionButtonVariant;
-  /** When true, disables the button and prevents interaction. */
-  disabled?: boolean;
-  /** Custom class merged with `.cinder-fab`. */
-  class?: string;
-  /**
-   * The icon (or icon + label for extended shape). Always provide `aria-label` when
-   * the FAB renders an icon without visible text — i.e. the `filled` shape.
-   */
-  children?: Snippet;
-};
-
-/**
- * Button-rendered FAB — no `href` prop.
- * The `type` attribute is omitted because the component always renders `type="button"`.
- */
-type FloatingActionButtonOnly = SharedBase &
-  Omit<HTMLButtonAttributes, 'class' | 'type' | 'disabled'> & { href?: undefined };
-
-/**
- * Link-rendered FAB — requires an `href` prop, renders as `<a>`.
- */
-type FloatingActionButtonLink = SharedBase & Omit<HTMLAnchorAttributes, 'class'> & { href: string };
-
-/**
- * Props for the FloatingActionButton component.
- *
- * Icon-only usage (i.e. `shape="filled"`) requires an accessible name via
- * `aria-label` or `aria-labelledby`. The component emits a dev-mode warning when
- * neither is present.
- */
-export type FloatingActionButtonProps = FloatingActionButtonOnly | FloatingActionButtonLink;
-
-/**
- * Cinder-specific props for the FloatingActionButton component, used by the schema generator.
- * Excludes the inherited HTML attribute surface.
- */
-export interface FloatingActionButtonSchemaProps {
-  /**
-   * Shape. `filled` = circle, `extended` = pill.
-   * @default "filled"
-   */
-  shape?: FloatingActionButtonShape;
-  /**
-   * Size of the FAB.
-   * @default "md"
-   */
-  size?: FloatingActionButtonSize;
-  /**
-   * Color palette.
-   * @default "primary"
-   */
-  variant?: FloatingActionButtonVariant;
-  /**
-   * When true, disables the button and prevents interaction.
-   * @default false
-   */
-  disabled?: boolean;
-  /** Render as an anchor `<a>` element with this href. */
-  href?: string;
-  /** Custom class merged with `.cinder-fab`. */
-  class?: string;
-}

package/src/components/floating-action-button/index.ts

@@ -1,11 +0,0 @@
-import './floating-action-button.css';
-import FloatingActionButton from './floating-action-button.svelte';
-
-export default FloatingActionButton;
-export type {
-  FloatingActionButtonProps,
-  FloatingActionButtonShape,
-  FloatingActionButtonSize,
-  FloatingActionButtonVariant,
-} from './floating-action-button.types.ts';
-export { FloatingActionButton };

package/src/components/focus-trap/focus-trap.svelte

@@ -1,45 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category overlay
-   * @status stable
-   * @purpose Headless focus-trap primitive that keeps Tab navigation within a container and restores focus on teardown.
-   * @tag overlay
-   * @tag accessibility
-   * @useWhen Building non-native overlays or popovers that need contained keyboard focus.
-   * @useWhen Reusing the same focus-management behavior across custom floating surfaces.
-   * @avoidWhen The surface already uses native dialog focus trapping.
-   * @related modal, drawer, sheet, popover
-   */
-  export type { FocusTrapProps } from './focus-trap.types.ts';
-</script>
-
-<script lang="ts">
-  import { classNames } from '../../utilities/class-names.ts';
-
-  import type { FocusTrapProps } from './focus-trap.types.ts';
-  import { createFocusTrap } from './focus-trap.utilities.svelte.ts';
-
-  let {
-    active = true,
-    restoreFocus = true,
-    initialFocus = null,
-    fallbackFocus = null,
-    class: className,
-    children,
-    ...rest
-  }: FocusTrapProps = $props();
-</script>
-
-<div
-  {@attach createFocusTrap({
-    active: () => active,
-    restoreFocus,
-    initialFocus: () => initialFocus,
-    fallbackFocus: () => fallbackFocus,
-  })}
-  class={classNames(className)}
-  {...rest}
->
-  {@render children()}
-</div>

package/src/components/focus-trap/focus-trap.types.ts

@@ -1,28 +0,0 @@
-import type { Snippet } from 'svelte';
-import type { HTMLAttributes } from 'svelte/elements';
-
-import type { FocusTargetInput, FocusTrapOptions } from './focus-trap.utilities.svelte.ts';
-
-export type FocusTrapProps = Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> & {
-  children: Snippet;
-  active?: boolean;
-  restoreFocus?: boolean;
-  initialFocus?: Exclude<FocusTargetInput, Function>;
-  fallbackFocus?: Exclude<FocusTargetInput, Function>;
-  class?: string;
-};
-
-export interface FocusTrapSchemaProps {
-  /** When true (default), Tab key navigation is constrained within the trap container. Set to false to temporarily suspend trapping without unmounting. */
-  active?: boolean;
-  /** When true (default), returns focus to the previously focused element when the trap is deactivated or unmounted. */
-  restoreFocus?: boolean;
-  /** CSS selector for the element that should receive focus when the trap activates. Falls back to `fallbackFocus` when the selector matches nothing. */
-  initialFocus?: string | null;
-  /** CSS selector for the element that receives focus when `initialFocus` is unset or unresolvable. Defaults to the trap container itself. */
-  fallbackFocus?: string | null;
-  /** Additional class applied to the focus-trap wrapper element. */
-  class?: string;
-}
-
-export type { FocusTrapOptions };

package/src/components/focus-trap/focus-trap.utilities.svelte.ts

@@ -1,297 +0,0 @@
-import type { Attachment } from 'svelte/attachments';
-
-import { restoreFocusTo } from '../../utilities/focus.ts';
-import { readOption } from '../../utilities/read-option.ts';
-
-export type FocusTargetInput =
-  | HTMLElement
-  | string
-  | null
-  | undefined
-  | (() => HTMLElement | string | null | undefined);
-
-export type FocusTrapOptions = {
-  active?: boolean | (() => boolean);
-  restoreFocus?: boolean;
-  initialFocus?: FocusTargetInput;
-  fallbackFocus?: FocusTargetInput;
-  /**
-   * Whether the trap moves focus into its panel when it activates. Defaults to
-   * `true` — the trap focuses {@link initialFocus} → first tabbable → fallback →
-   * the root on open, which is what stand-alone overlays (popovers, menus) want.
-   *
-   * Set to `false` for hosts that perform their OWN initial focus (native
-   * `<dialog>.showModal()` already focuses, and Modal/Sheet/Drawer then deliberately
-   * move focus to a `tabindex="-1"` body container so reading starts at the content,
-   * not the close button). With `manageInitialFocus: false` the trap still provides
-   * Tab-wrapping and trap-stack membership, but never overrides the host's chosen
-   * initial focus. Such hosts also own focus restoration, so they pair this with
-   * `restoreFocus: false`.
-   */
-  manageInitialFocus?: boolean;
-};
-
-type TrapInstance = {
-  id: symbol;
-  node: HTMLElement;
-};
-
-const trapStack: TrapInstance[] = [];
-
-const FOCUSABLE_SELECTOR = [
-  'a[href]',
-  'button:not([disabled])',
-  'input:not([disabled])',
-  'select:not([disabled])',
-  'textarea:not([disabled])',
-  'summary',
-  '[tabindex]:not([tabindex="-1"])',
-  '[contenteditable]:not([contenteditable="false"])',
-].join(', ');
-
-function noop() {}
-
-function isHiddenByTree(element: HTMLElement): boolean {
-  if (element.hidden) return true;
-  if (element.matches('[inert], [aria-hidden="true"]')) return true;
-  const ancestor = element.closest<HTMLElement>('[hidden], [inert], [aria-hidden="true"]');
-  return ancestor !== null && ancestor !== element;
-}
-
-/**
- * Whether an element is eligible to receive focus via Tab. Excludes `tabindex="-1"` because that
- * value opts an element out of sequential focus navigation — used for auto-discovery in
- * `getTabbableElements`.
- */
-function isFocusableCandidate(element: HTMLElement): boolean {
-  if (isHiddenByTree(element)) return false;
-  if (element.hasAttribute('disabled')) return false;
-  // Reject ALL explicit negative tabindex values (not just "-1"). `tabindex="-2"`
-  // is programmatically focusable but NOT reachable via sequential Tab, so
-  // including it in `getTabbableElements` would corrupt the first/last boundary
-  // the Tab-wrap logic relies on. Gate on `hasAttribute` first so the IDL
-  // `tabIndex` property is only read for elements that actually set it — natively
-  // focusable elements without the attribute keep their default tabbability
-  // without depending on the DOM environment's IDL defaults (happy-dom vs real).
-  if (element.hasAttribute('tabindex') && element.tabIndex < 0) return false;
-  return true;
-}
-
-const NATIVELY_FOCUSABLE_TAGS = new Set(['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY']);
-
-/**
- * Whether an element can be programmatically focused via `.focus()`. Unlike `isFocusableCandidate`,
- * this accepts `tabindex="-1"` — the standard pattern for making a non-interactive element
- * (a container, heading, etc.) a valid `initialFocus`/`fallbackFocus` target without inserting it
- * into the Tab order. Requires the element to actually be capable of accepting focus: a
- * `tabindex` attribute, a natively focusable tag, an anchor with `href`, or contenteditable.
- * Plain `<div>` / `<h2>` etc. without `tabindex` are rejected because `.focus()` is a no-op on
- * them in real browsers — accepting them would silently leave focus outside the trap.
- */
-function isProgrammaticallyFocusable(element: HTMLElement): boolean {
-  if (isHiddenByTree(element)) return false;
-  if (element.hasAttribute('disabled')) return false;
-  if (element.hasAttribute('tabindex')) return true;
-  if (NATIVELY_FOCUSABLE_TAGS.has(element.tagName)) return true;
-  if (element.tagName === 'A' && element.hasAttribute('href')) return true;
-  const contentEditable = element.getAttribute('contenteditable');
-  if (contentEditable !== null && contentEditable !== 'false') return true;
-  return false;
-}
-
-function getTabbableElements(root: HTMLElement): HTMLElement[] {
-  return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
-    (element) => root.contains(element) && isFocusableCandidate(element),
-  );
-}
-
-function resolveScopedTarget(root: HTMLElement, target: FocusTargetInput): HTMLElement | null {
-  const resolved = readOption(target ?? null);
-  if (!resolved) return null;
-  if (typeof resolved === 'string') {
-    let match: HTMLElement | null = null;
-    try {
-      match = root.querySelector<HTMLElement>(resolved);
-    } catch {
-      return null;
-    }
-    return match && root.contains(match) ? match : null;
-  }
-  return resolved instanceof HTMLElement && root.contains(resolved) ? resolved : null;
-}
-
-function getFallbackTarget(root: HTMLElement, fallbackFocus: FocusTargetInput): HTMLElement | null {
-  const resolved = resolveScopedTarget(root, fallbackFocus);
-  return resolved && isProgrammaticallyFocusable(resolved) ? resolved : null;
-}
-
-/**
- * Calls `.focus()` and returns whether the element actually became `document.activeElement`.
- * `isProgrammaticallyFocusable` cannot tell whether a plain `<div>` or `<h2>` (no `tabindex`,
- * no native focus behavior) will accept focus — `.focus()` is a no-op on those. Verifying the
- * landing lets callers fall through to the next strategy instead of silently leaving focus
- * outside the trap.
- */
-function tryFocus(element: HTMLElement): boolean {
-  element.focus();
-  return document.activeElement === element;
-}
-
-function ensureRootFocusable(root: HTMLElement): () => void {
-  if (root.hasAttribute('tabindex')) {
-    return () => {};
-  }
-  root.setAttribute('tabindex', '-1');
-  return () => {
-    root.removeAttribute('tabindex');
-  };
-}
-
-function pushTrap(instance: TrapInstance) {
-  const existingIndex = trapStack.findIndex((entry) => entry.id === instance.id);
-  if (existingIndex !== -1) {
-    trapStack.splice(existingIndex, 1);
-  }
-  trapStack.push(instance);
-}
-
-function removeTrap(id: symbol) {
-  const index = trapStack.findIndex((entry) => entry.id === id);
-  if (index !== -1) {
-    trapStack.splice(index, 1);
-  }
-}
-
-function isTopTrap(id: symbol): boolean {
-  return trapStack.at(-1)?.id === id;
-}
-
-export function createFocusTrap(options: FocusTrapOptions = {}): Attachment<HTMLElement> {
-  const trapId = Symbol('focus-trap');
-
-  return (node) => {
-    const isActive = () => readOption(options.active ?? true);
-    const restoreFocus = options.restoreFocus ?? true;
-    const initialFocus = options.initialFocus ?? null;
-    const fallbackFocus = options.fallbackFocus ?? null;
-    const manageInitialFocus = options.manageInitialFocus ?? true;
-
-    let activated = false;
-    // Bumped on every `activate()`. The deferred `focusTrapTarget` microtask snapshots this value
-    // and bails if it no longer matches, so a deactivate (or deactivate→reactivate) that lands
-    // before the microtask drains can't let a stale activation steal focus into the trap.
-    let activationGeneration = 0;
-    let capturedFocus: HTMLElement | null = null;
-    let restoreRootFocusability = noop;
-
-    function focusTrapTarget() {
-      const preferred = resolveScopedTarget(node, initialFocus);
-      if (preferred && isProgrammaticallyFocusable(preferred) && tryFocus(preferred)) {
-        return;
-      }
-
-      const tabbable = getTabbableElements(node);
-      if (tabbable.length > 0 && tabbable[0] && tryFocus(tabbable[0])) {
-        return;
-      }
-
-      const fallbackTarget = getFallbackTarget(node, fallbackFocus);
-      if (fallbackTarget && tryFocus(fallbackTarget)) {
-        return;
-      }
-
-      restoreRootFocusability = ensureRootFocusable(node);
-      node.focus();
-    }
-
-    function activate() {
-      if (activated) return;
-      activated = true;
-      const generation = ++activationGeneration;
-      capturedFocus =
-        document.activeElement instanceof HTMLElement && document.activeElement !== document.body
-          ? document.activeElement
-          : null;
-      pushTrap({ id: trapId, node });
-      // Hosts that own their own initial focus (Modal/Sheet/Drawer focus a body
-      // container after showModal()) opt out so the trap never overrides that choice
-      // by yanking focus to the first tabbable (the close button) on the next microtask.
-      if (!manageInitialFocus) return;
-      // Defer focusing so the trap's content is in the DOM. Guard against the trap being
-      // deactivated (or deactivated then reactivated) before this microtask drains — moving focus
-      // into a no-longer-current activation would steal it back after `deactivate()` already
-      // restored it to the previously-focused element. The `!isActive()` check covers the
-      // synchronous open→close window: `deactivate()` runs on the next effect flush (after this
-      // microtask), but the live reactive `active` getter already reads false, so a host that
-      // closes immediately after opening does not have focus dragged into the trap post-close.
-      queueMicrotask(() => {
-        if (!activated || generation !== activationGeneration || !isActive()) return;
-        focusTrapTarget();
-      });
-    }
-
-    function deactivate() {
-      if (!activated) return;
-      activated = false;
-      restoreRootFocusability();
-      restoreRootFocusability = noop;
-      removeTrap(trapId);
-      if (restoreFocus) {
-        restoreFocusTo(capturedFocus);
-      }
-      capturedFocus = null;
-    }
-
-    function handleKeydown(event: KeyboardEvent) {
-      // Use the live `isActive()` value so a trap deactivated reactively stops intercepting Tab
-      // immediately, even if the cleanup branch below has not yet fired (which only runs on
-      // unmount, not on prop changes).
-      if (!isActive() || !isTopTrap(trapId) || event.key !== 'Tab') return;
-
-      const tabbable = getTabbableElements(node);
-      if (tabbable.length === 0) {
-        const fallbackTarget = getFallbackTarget(node, fallbackFocus);
-        event.preventDefault();
-        if (!fallbackTarget || !tryFocus(fallbackTarget)) {
-          restoreRootFocusability = ensureRootFocusable(node);
-          node.focus();
-        }
-        return;
-      }
-
-      const first = tabbable[0];
-      const last = tabbable[tabbable.length - 1];
-      const activeElement = document.activeElement;
-
-      if (event.shiftKey && activeElement === first) {
-        event.preventDefault();
-        last?.focus();
-      } else if (!event.shiftKey && activeElement === last) {
-        event.preventDefault();
-        first?.focus();
-      }
-    }
-
-    node.addEventListener('keydown', handleKeydown);
-
-    // Reactive activation: a getter-form `active` flipping true→false (or vice versa) must call
-    // `activate()` / `deactivate()` immediately, not only on unmount. Otherwise an inactive trap
-    // lingers on `trapStack`, blocking lower traps' Tab handling via `isTopTrap`, and focus is
-    // never restored to the previously-focused element on reactive deactivation.
-    $effect(() => {
-      if (!isActive()) return;
-      activate();
-      return () => {
-        deactivate();
-      };
-    });
-
-    return () => {
-      node.removeEventListener('keydown', handleKeydown);
-      // `$effect` cleanup above already ran `deactivate()` when active flipped false; this final
-      // call is a defensive no-op in that case (guarded by the `activated` flag) and ensures
-      // restoration when the trap is still active at unmount.
-      deactivate();
-    };
-  };
-}

package/src/components/focus-trap/index.ts

@@ -1,6 +0,0 @@
-import FocusTrap from './focus-trap.svelte';
-
-export default FocusTrap;
-export type { FocusTrapOptions, FocusTrapProps } from './focus-trap.types.ts';
-export { createFocusTrap } from './focus-trap.utilities.svelte.ts';
-export { FocusTrap };

package/src/components/footer/footer.svelte

@@ -1,79 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category layout
-   * @status beta
-   * @purpose Footer composition primitive with brand copy, grouped links, and legal row content.
-   * @tag layout
-   * @tag navigation
-   * @tag footer
-   * @useWhen Building page-level footer chrome with grouped resource links and legal text.
-   * @useWhen Keeping lower-page wayfinding and compliance links in one responsive region.
-   * @avoidWhen You need top-level route switching with active state handling. | navigation-bar
-   * @avoidWhen You need dense in-content navigation rather than page chrome.
-   * @related navigation-bar, side-navigation, container, grid
-   */
-  export type { FooterGroup, FooterLink, FooterProps } from './footer.types.ts';
-</script>
-
-<script lang="ts">
-  import { classNames } from '../../utilities/class-names.ts';
-  import type { FooterProps } from './footer.types.ts';
-
-  let {
-    brand,
-    description,
-    groups = [],
-    legalLinks = [],
-    copyright,
-    label = 'Footer',
-    class: className,
-    ...rest
-  }: FooterProps = $props();
-</script>
-
-<footer {...rest} class={classNames('cinder-footer', className)} aria-label={label}>
-  <div class="cinder-footer__main">
-    {#if brand || description}
-      <section class="cinder-footer__brand">
-        {#if brand}
-          <h2 class="cinder-footer__brand-title">{brand}</h2>
-        {/if}
-        {#if description}
-          <p class="cinder-footer__brand-description">{description}</p>
-        {/if}
-      </section>
-    {/if}
-
-    {#if groups.length > 0}
-      <div class="cinder-footer__groups">
-        {#each groups as group (group.id)}
-          <nav aria-label={group.title}>
-            <h3 class="cinder-footer__group-title">{group.title}</h3>
-            <ul class="cinder-footer__list">
-              {#each group.links as link (link.id)}
-                <li><a class="cinder-footer__link" href={link.href}>{link.label}</a></li>
-              {/each}
-            </ul>
-          </nav>
-        {/each}
-      </div>
-    {/if}
-  </div>
-
-  {#if copyright || legalLinks.length > 0}
-    <div class="cinder-footer__legal">
-      {#if copyright}
-        <span>{copyright}</span>
-      {/if}
-
-      {#if legalLinks.length > 0}
-        <ul class="cinder-footer__legal-links">
-          {#each legalLinks as link (link.id)}
-            <li><a class="cinder-footer__link" href={link.href}>{link.label}</a></li>
-          {/each}
-        </ul>
-      {/if}
-    </div>
-  {/if}
-</footer>

package/src/components/footer/footer.types.ts

@@ -1,30 +0,0 @@
-import type { HTMLAttributes } from 'svelte/elements';
-
-export type FooterLink = {
-  id: string;
-  label: string;
-  href: string;
-};
-
-export type FooterGroup = {
-  id: string;
-  title: string;
-  links: FooterLink[];
-};
-
-export type FooterProps = Omit<HTMLAttributes<HTMLElement>, 'children' | 'class'> & {
-  /** Optional brand/title text rendered in the first column. */
-  brand?: string;
-  /** Optional supporting copy rendered under brand. */
-  description?: string;
-  /** Link groups rendered as columns in the main area. */
-  groups?: FooterGroup[];
-  /** Additional links rendered in the legal row. */
-  legalLinks?: FooterLink[];
-  /** Copyright text in the legal row. */
-  copyright?: string;
-  /** Accessible label for the footer landmark. */
-  label?: string;
-  /** Additional classes merged on the root element. */
-  class?: string;
-};

package/src/components/footer/index.ts

@@ -1,6 +0,0 @@
-import './footer.css';
-import Footer from './footer.svelte';
-
-export default Footer;
-export type { FooterGroup, FooterLink, FooterProps } from './footer.types.ts';
-export { Footer };