@lostgradient/cinder 0.5.0 → 0.6.0

package/src/components/form-field/form-field.svelte

@@ -1,98 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category form
-   * @status stable
-   * @purpose Wrapper primitive that pairs a single control with its label, description, and error and wires the ARIA association via context.
-   * @tag form
-   * @tag wrapper
-   * @useWhen Composing a one-off field where the input does not own its own label rendering.
-   * @useWhen Forwarding shared required, disabled, and error state to an opted-in child control.
-   * @avoidWhen Grouping multiple related controls under one heading — use form-section instead.
-   * @related form-section, label, input
-   */
-  export type { FormFieldProps } from './form-field.types.ts';
-</script>
-
-<script lang="ts">
-  import type { FormFieldProps } from './form-field.types.ts';
-  import {
-    ariaInvalid,
-    composeDescribedBy,
-    describeId,
-    errorId as buildErrorId,
-  } from '../../_internal/field-control.ts';
-  import { setFormFieldContext } from '../../_internal/form-field-context.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-
-  let {
-    id,
-    label,
-    description,
-    error,
-    required = false,
-    disabled = false,
-    class: className,
-    children,
-  }: FormFieldProps = $props();
-
-  const labelId = $derived(`${id}-label`);
-  const descriptionId = $derived(describeId(id, !!description));
-  const errorId = $derived(buildErrorId(id, !!error));
-  const describedBy = $derived(composeDescribedBy(descriptionId, errorId));
-  const invalid = $derived(ariaInvalid(!!error));
-
-  setFormFieldContext({
-    get controlId() {
-      return id;
-    },
-    get labelId() {
-      return labelId;
-    },
-    get describedBy() {
-      return describedBy;
-    },
-    get descriptionId() {
-      return descriptionId;
-    },
-    get errorId() {
-      return errorId;
-    },
-    get invalid() {
-      return invalid;
-    },
-    get required() {
-      return required;
-    },
-    get disabled() {
-      return disabled;
-    },
-  });
-</script>
-
-<div class={classNames('cinder-form-field', className)}>
-  <label
-    id={labelId}
-    for={id}
-    class="cinder-form-field__label"
-    data-disabled={disabled || undefined}
-  >
-    {label}
-    {#if required}
-      <!-- Visible asterisk conveys "required" by shape, not color alone (WCAG
-           1.4.1). aria-hidden so the accessible name stays clean — the field's
-           own `required`/`aria-required` attribute is the single AT signal. -->
-      <span class="cinder-_required-marker" aria-hidden="true">*</span>
-    {/if}
-  </label>
-
-  {@render children()}
-
-  {#if description}
-    <p id={descriptionId} class="cinder-form-field__description">{description}</p>
-  {/if}
-
-  {#if error}
-    <p id={errorId} class="cinder-form-field__error" aria-live="polite">{error}</p>
-  {/if}
-</div>

package/src/components/form-field/form-field.types.ts

@@ -1,19 +0,0 @@
-import type { Snippet } from 'svelte';
-export type FormFieldProps = {
-  /** Required stable id — used for `<label for>`, description, error, and the child control's id via context. */
-  id: string;
-  /** Visible label text. Required — the primitive's whole purpose is label association. */
-  label: string;
-  /** Helper text rendered below the control; wired into `aria-describedby`. */
-  description?: string;
-  /** Validation error; sets `aria-invalid="true"` on opted-in controls via context. */
-  error?: string;
-  /** Renders a visual required marker and exposes `required: true` on the context. */
-  required?: boolean;
-  /** Propagated to opted-in controls via context. Does not style FormField itself. */
-  disabled?: boolean;
-  /** Additional class merged with `.cinder-form-field`. */
-  class?: string;
-  /** Control(s) rendered inside the field. */
-  children: Snippet;
-};

package/src/components/form-field/index.ts

@@ -1,6 +0,0 @@
-import './form-field.css';
-import FormField from './form-field.svelte';
-
-export default FormField;
-export type { FormFieldProps } from './form-field.types.ts';
-export { FormField };

package/src/components/form-section/form-section.svelte

@@ -1,80 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category form
-   * @status stable
-   * @purpose Sectioning wrapper that groups related form fields under a heading or legend and applies a responsive column layout.
-   * @tag form
-   * @tag layout
-   * @useWhen Splitting a long form into labelled segments such as "Account" or "Billing".
-   * @useWhen Rendering a fieldset with a legend for a set of tightly related inputs.
-   * @avoidWhen Wrapping a single control with its label and error — use form-field instead.
-   * @related form-field, section-heading
-   */
-  const headingTags: Record<FormSectionHeadingLevel, string> = {
-    2: 'h2',
-    3: 'h3',
-    4: 'h4',
-    5: 'h5',
-    6: 'h6',
-  };
-
-  export type { FormSectionHeadingLevel, FormSectionProps } from './form-section.types.ts';
-</script>
-
-<script lang="ts">
-  import type { FormSectionHeadingLevel, FormSectionProps } from './form-section.types.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-  import { devWarn } from '../../utilities/dev-warn.ts';
-
-  let {
-    as = 'section',
-    heading,
-    headingLevel = 2,
-    description,
-    columns = 2,
-    class: className,
-    children,
-  }: FormSectionProps = $props();
-
-  // Re-check reactively: `as` and `heading` are ordinary (non-bindable) props
-  // that a parent can change on re-render, so the warning must fire whenever the
-  // combination becomes invalid, not only at mount. devWarn self-gates on DEV.
-  $effect(() => {
-    if (as === 'fieldset' && !heading) {
-      devWarn(
-        '[cinder/FormSection] `as="fieldset"` requires a `heading` prop — a fieldset without a legend has no accessible group name.',
-      );
-    }
-  });
-
-  const headingTag = $derived(headingTags[headingLevel as FormSectionHeadingLevel] ?? 'h2');
-</script>
-
-{#if as === 'fieldset'}
-  <fieldset class={classNames('cinder-form-section', className)} data-columns={columns}>
-    {#if heading}
-      <legend class="cinder-form-section__legend">{heading}</legend>
-    {/if}
-    {#if description}
-      <p class="cinder-form-section__description">{description}</p>
-    {/if}
-    <div class="cinder-form-section__grid">
-      {@render children()}
-    </div>
-  </fieldset>
-{:else}
-  <section class={classNames('cinder-form-section', className)} data-columns={columns}>
-    {#if heading}
-      <svelte:element this={headingTag} class="cinder-form-section__heading">
-        {heading}
-      </svelte:element>
-    {/if}
-    {#if description}
-      <p class="cinder-form-section__description">{description}</p>
-    {/if}
-    <div class="cinder-form-section__grid">
-      {@render children()}
-    </div>
-  </section>
-{/if}

package/src/components/form-section/form-section.types.ts

@@ -1,34 +0,0 @@
-import type { Snippet } from 'svelte';
-export type FormSectionHeadingLevel = 2 | 3 | 4 | 5 | 6;
-type FormSectionSharedProps = {
-  /** Optional descriptive paragraph rendered under the heading/legend. */
-  description?: string;
-  /** Column ceiling. Container queries pick the actual rendered count. Default 2. */
-  columns?: 1 | 2 | 3 | 4;
-  /** Additional class merged with `.cinder-form-section`. */
-  class?: string;
-  /** Children (FormField instances or arbitrary content). */
-  children: Snippet;
-};
-/**
- * Discriminated union: `as="fieldset"` requires `heading` (a legend-less fieldset
- * has no accessible group name). `as="section"` (default) treats heading as optional.
- * This makes the inaccessible state unrepresentable in TypeScript.
- */
-export type FormSectionProps =
-  | (FormSectionSharedProps & {
-      /** Wrapper element. Default. */
-      as?: 'section';
-      /** Heading text rendered as `<h{level}>`. */
-      heading?: string;
-      /** Heading level. Default 2. */
-      headingLevel?: FormSectionHeadingLevel;
-    })
-  | (FormSectionSharedProps & {
-      /** Wrapper element. Use for grouped related inputs. */
-      as: 'fieldset';
-      /** Required heading — rendered as `<legend>`. */
-      heading: string;
-      /** Ignored for fieldset (legend is the only heading). */
-      headingLevel?: never;
-    });

package/src/components/form-section/index.ts

@@ -1,6 +0,0 @@
-import './form-section.css';
-import FormSection from './form-section.svelte';
-
-export default FormSection;
-export type { FormSectionHeadingLevel, FormSectionProps } from './form-section.types.ts';
-export { FormSection };

package/src/components/grid/grid.svelte

@@ -1,62 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category layout
-   * @status beta
-   * @purpose CSS grid container for explicit columns, intrinsic auto-fill layouts, and two-dimensional placement.
-   * @tag layout
-   * @tag grid
-   * @useWhen Building form layouts, card grids, or dashboards that need two-dimensional placement.
-   * @useWhen Creating intrinsic responsive grids by passing minItemWidth.
-   * @avoidWhen Presenting homogeneous gallery tiles - use grid-list instead. | grid-list
-   * @avoidWhen Packing variable-height content into waterfall columns - use masonry instead. | masonry
-   * @related grid-item, grid-list, masonry
-   */
-  export type { GridColumns, GridProps } from './grid.types.ts';
-</script>
-
-<script lang="ts">
-  import { classNames } from '../../utilities/class-names.ts';
-  import type { GridProps } from './grid.types.ts';
-
-  let {
-    columns,
-    gap,
-    rowGap,
-    columnGap,
-    minItemWidth,
-    as = 'div',
-    class: customClassName,
-    children,
-    ...rest
-  }: GridProps = $props();
-
-  const resolvedMinItemWidth = $derived(
-    typeof minItemWidth === 'string' && minItemWidth.length > 0 ? minItemWidth : undefined,
-  );
-
-  const resolvedColumns = $derived.by(() => {
-    if (resolvedMinItemWidth) {
-      return 'repeat(auto-fill, minmax(min(var(--cinder-grid-min-item-width), 100%), 1fr))';
-    }
-
-    if (typeof columns === 'number') {
-      if (!Number.isInteger(columns) || columns < 1) return undefined;
-      return `repeat(${columns}, 1fr)`;
-    }
-    if (typeof columns === 'string' && columns.length > 0) return columns;
-    return undefined;
-  });
-</script>
-
-<svelte:element
-  this={as}
-  {...rest}
-  class={classNames('cinder-grid', customClassName)}
-  style:--cinder-grid-columns={resolvedColumns}
-  style:--cinder-grid-row-gap={rowGap ?? gap}
-  style:--cinder-grid-column-gap={columnGap ?? gap}
-  style:--cinder-grid-min-item-width={resolvedMinItemWidth}
->
-  {@render children?.()}
-</svelte:element>

package/src/components/grid/grid.types.ts

@@ -1,31 +0,0 @@
-import type { Snippet } from 'svelte';
-import type { HTMLAttributes } from 'svelte/elements';
-
-/** Column definition accepted by Grid. */
-export type GridColumns = number | string;
-
-/** Props for the Grid component. */
-export type GridProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
-  /**
-   * Positive integer number of equal-width columns or a full CSS `grid-template-columns` value.
-   * Numeric values render as `repeat(<columns>, 1fr)`.
-   */
-  columns?: GridColumns;
-  /** Uniform row and column gap. */
-  gap?: string;
-  /** Row gap override. Wins over `gap` for rows. */
-  rowGap?: string;
-  /** Column gap override. Wins over `gap` for columns. */
-  columnGap?: string;
-  /**
-   * Minimum item width for an intrinsic auto-fill grid. When present, this takes
-   * precedence over `columns`.
-   */
-  minItemWidth?: string;
-  /** Rendered HTML tag. */
-  as?: string;
-  /** Custom class merged with `.cinder-grid`. */
-  class?: string;
-  /** Grid contents. */
-  children: Snippet;
-};

package/src/components/grid/index.ts

@@ -1,17 +0,0 @@
-import GridItem from '../grid-item/grid-item.svelte';
-import './grid.css';
-import GridRoot from './grid.svelte';
-
-/**
- * `Grid` is the parent compound component and a namespace exposing the optional
- * placement leaf as `Grid.Item`. The leaf remains importable individually from
- * `@lostgradient/cinder/grid-item`.
- */
-const Grid = Object.assign(GridRoot, {
-  Item: GridItem,
-});
-
-export default Grid;
-export type { GridItemProps } from '../grid-item/grid-item.types.ts';
-export type { GridColumns, GridProps } from './grid.types.ts';
-export { Grid };

package/src/components/grid-item/grid-item.svelte

@@ -1,55 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category layout
-   * @status beta
-   * @purpose Optional placement child for Grid that controls column and row spans or explicit track placement.
-   * @tag layout
-   * @tag grid
-   * @useWhen A child in a grid needs to span tracks or start at a specific track.
-   * @avoidWhen Every child can use default grid auto-placement - render plain children inside Grid instead. | grid
-   * @related grid
-   */
-  export type { GridItemProps } from './grid-item.types.ts';
-</script>
-
-<script lang="ts">
-  import { classNames } from '../../utilities/class-names.ts';
-  import type { GridItemProps } from './grid-item.types.ts';
-
-  let {
-    span,
-    columnStart,
-    columnEnd,
-    rowSpan,
-    rowStart,
-    as = 'div',
-    class: customClassName,
-    children,
-    ...rest
-  }: GridItemProps = $props();
-
-  const columnSpan = $derived(span !== undefined ? String(span) : undefined);
-  const resolvedColumnStart = $derived(columnStart !== undefined ? String(columnStart) : undefined);
-  const resolvedColumnEnd = $derived(columnEnd !== undefined ? String(columnEnd) : undefined);
-  const resolvedRowSpan = $derived(rowSpan !== undefined ? String(rowSpan) : undefined);
-  const resolvedRowStart = $derived(rowStart !== undefined ? String(rowStart) : undefined);
-  const shouldApplyColumnSpan = $derived(
-    columnSpan !== undefined && resolvedColumnEnd === undefined,
-  );
-</script>
-
-<svelte:element
-  this={as}
-  {...rest}
-  class={classNames('cinder-grid-item', customClassName)}
-  data-cinder-column-span={shouldApplyColumnSpan ? 'true' : undefined}
-  data-cinder-row-span={resolvedRowSpan !== undefined ? 'true' : undefined}
-  style:--cinder-grid-item-column-span={columnSpan}
-  style:--cinder-grid-item-column-start={resolvedColumnStart}
-  style:--cinder-grid-item-column-end={resolvedColumnEnd}
-  style:--cinder-grid-item-row-span={resolvedRowSpan}
-  style:--cinder-grid-item-row-start={resolvedRowStart}
->
-  {@render children?.()}
-</svelte:element>

package/src/components/grid-item/grid-item.types.ts

@@ -1,22 +0,0 @@
-import type { Snippet } from 'svelte';
-import type { HTMLAttributes } from 'svelte/elements';
-
-/** Props for the GridItem component. */
-export type GridItemProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
-  /** Number of columns this item spans. */
-  span?: number | string;
-  /** Explicit `grid-column-start` value. */
-  columnStart?: number | string;
-  /** Explicit `grid-column-end` value. */
-  columnEnd?: number | string;
-  /** Number of rows this item spans. */
-  rowSpan?: number | string;
-  /** Explicit `grid-row-start` value. */
-  rowStart?: number | string;
-  /** Rendered HTML tag. */
-  as?: string;
-  /** Custom class merged with `.cinder-grid-item`. */
-  class?: string;
-  /** Grid item contents. */
-  children: Snippet;
-};

package/src/components/grid-item/index.ts

@@ -1,5 +0,0 @@
-import GridItem from './grid-item.svelte';
-
-export default GridItem;
-export type { GridItemProps } from './grid-item.types.ts';
-export { GridItem };

package/src/components/grid-list/grid-list.svelte

@@ -1,36 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category data-display
-   * @status stable
-   * @purpose Responsive grid container that arranges grid-list-item tiles into auto-sized columns.
-   * @tag grid
-   * @tag gallery
-   * @useWhen Presenting a homogenous collection of cards that should reflow into multiple columns.
-   * @useWhen Constraining tile minimum widths per breakpoint via the minColumnWidth prop.
-   * @avoidWhen Comparing rows of structured data — use table instead.
-   * @avoidWhen Stacking dense list rows vertically — use stacked-list-item instead.
-   * @related grid-list-item, table
-   */
-  export type { GridListProps } from './grid-list.types.ts';
-</script>
-
-<script lang="ts">
-  import type { GridListProps } from './grid-list.types.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-
-  let { minColumnWidth, class: className, children, ...rest }: GridListProps = $props();
-
-  const minWidth = $derived(
-    minColumnWidth && minColumnWidth.length > 0 ? minColumnWidth : undefined,
-  );
-</script>
-
-<ul
-  {...rest}
-  role="list"
-  class={classNames('cinder-grid-list', className)}
-  style:--cinder-grid-list-min-width={minWidth}
->
-  {@render children()}
-</ul>

package/src/components/grid-list/grid-list.types.ts

@@ -1,15 +0,0 @@
-import type { Snippet } from 'svelte';
-import type { HTMLAttributes } from 'svelte/elements';
-export type GridListProps = Omit<HTMLAttributes<HTMLUListElement>, 'role'> & {
-  /**
-   * Minimum width of each grid cell, expressed as a CSS `<length>` value
-   * (e.g. `"16rem"`, `"240px"`, `"min(20rem, 100%)"`). Used as the first
-   * argument to `minmax()` inside a `repeat(auto-fill, ...)` track.
-   * Default: `"16rem"`. Empty string is treated as unset.
-   */
-  minColumnWidth?: string;
-  /** Extra class names merged with `cinder-grid-list`. */
-  class?: string;
-  /** Items — typically `GridListItem` instances. */
-  children: Snippet;
-};

package/src/components/grid-list/index.ts

@@ -1,16 +0,0 @@
-import GridListItem from '../grid-list-item/grid-list-item.svelte';
-import './grid-list.css';
-import GridListRoot from './grid-list.svelte';
-
-/**
- * `GridList` is the parent compound component and a namespace exposing the
- * compose-only `GridList.Item` leaf. The leaf remains importable individually
- * via `@lostgradient/cinder/grid-list-item`.
- */
-const GridList = Object.assign(GridListRoot, {
-  Item: GridListItem,
-});
-
-export default GridList;
-export type { GridListProps } from './grid-list.types.ts';
-export { GridList };

package/src/components/grid-list-item/grid-list-item.svelte

@@ -1,81 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category data-display
-   * @status stable
-   * @purpose Tile within a grid-list that combines an image, title, subtitle, meta, and action slots and may link via href.
-   * @tag grid
-   * @tag tile
-   * @useWhen Rendering a single card cell inside a grid-list parent.
-   * @useWhen Turning the tile into an anchor by passing href.
-   * @avoidWhen Standing alone outside a grid-list — it inherits the grid layout context.
-   * @related grid-list
-   */
-  export type { GridListItemProps } from './grid-list-item.types.ts';
-</script>
-
-<script lang="ts">
-  import type { GridListItemProps } from './grid-list-item.types.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-
-  let {
-    href,
-    target,
-    rel,
-    class: className,
-    image,
-    title,
-    subtitle,
-    meta,
-    actions,
-    ...rest
-  }: GridListItemProps = $props();
-
-  /**
-   * Compose `rel` for the stretched-link anchor.
-   * When target matches "_blank" (case-insensitive), merge "noopener" and
-   * "noreferrer" into whatever the consumer supplied, deduplicating tokens.
-   */
-  const composedRel = $derived.by(() => {
-    const isBlank = target?.toLowerCase() === '_blank';
-    if (!isBlank) return rel;
-    const tokens = new Set((rel ?? '').split(/\s+/).filter(Boolean));
-    tokens.add('noopener');
-    tokens.add('noreferrer');
-    return [...tokens].join(' ');
-  });
-</script>
-
-<li {...rest} class={classNames('cinder-grid-list__item', className)}>
-  {#if image}
-    <div class="cinder-grid-list__image">
-      {@render image()}
-    </div>
-  {/if}
-  {#if title}
-    <div class="cinder-grid-list__title">
-      {#if href !== undefined}
-        <a class="cinder-grid-list__link" {href} {target} rel={composedRel}>
-          {@render title()}
-        </a>
-      {:else}
-        {@render title()}
-      {/if}
-    </div>
-  {/if}
-  {#if subtitle}
-    <div class="cinder-grid-list__subtitle">
-      {@render subtitle()}
-    </div>
-  {/if}
-  {#if meta}
-    <div class="cinder-grid-list__meta">
-      {@render meta()}
-    </div>
-  {/if}
-  {#if actions}
-    <div class="cinder-grid-list__actions">
-      {@render actions()}
-    </div>
-  {/if}
-</li>

package/src/components/grid-list-item/grid-list-item.types.ts

@@ -1,53 +0,0 @@
-import type { Snippet } from 'svelte';
-import type { HTMLAnchorAttributes, HTMLAttributes } from 'svelte/elements';
-type LiEventAttribute = Extract<keyof HTMLAttributes<HTMLLIElement>, `on${string}`>;
-type GridListItemBase = Omit<
-  HTMLAttributes<HTMLLIElement>,
-  'title' | 'class' | 'role' | 'tabindex' | LiEventAttribute
-> & {
-  /** Additional class merged onto the `.cinder-grid-list__item` root element. */
-  class?: string;
-  /** Optional image region (avatar, thumbnail). */
-  image?: Snippet;
-  /** Primary label. Provides the accessible name for the stretched link when `href` is set. */
-  title?: Snippet;
-  /** Secondary description. */
-  subtitle?: Snippet;
-  /** Tertiary metadata (badges, supplementary text). */
-  meta?: Snippet;
-  /**
-   * Action buttons. This wrapper is lifted above the stretched-link overlay
-   * via `position: relative; z-index: 1` so buttons remain clickable.
-   */
-  actions?: Snippet;
-};
-/** Non-linkified item — no stretched-link overlay. */
-type GridListItemStatic = GridListItemBase & {
-  href?: never;
-  target?: never;
-  rel?: never;
-};
-/**
- * Linkified item — `title` becomes a stretched link covering the entire card
- * via a pseudo-element overlay. Only `actions` (and descendants marked with
- * `data-cinder-stretched-link-escape`) remain pointer-operable above the overlay.
- *
- * `title` is required when `href` is set: it provides the accessible name for
- * the stretched-link anchor. An item with `href` but no `title` would render a
- * pseudo-element overlay with no reachable `<a>` and no accessible name.
- */
-type GridListItemLinked = GridListItemBase & {
-  /** Destination URL. When set, the `title` snippet is rendered as a stretched `<a>` anchor covering the entire tile. */
-  href: string;
-  /** Required when href is set — provides the accessible name for the anchor. */
-  title: Snippet;
-  /**
-   * When `target` matches `"_blank"` (case-insensitive), the component
-   * automatically composes `rel="noopener noreferrer"` with any
-   * consumer-supplied `rel` tokens to prevent reverse-tabnapping.
-   */
-  target?: HTMLAnchorAttributes['target'];
-  /** `rel` attribute forwarded to the stretched-link anchor; `noopener noreferrer` is merged automatically when `target="_blank"`. */
-  rel?: HTMLAnchorAttributes['rel'];
-};
-export type GridListItemProps = GridListItemStatic | GridListItemLinked;

package/src/components/grid-list-item/index.ts

@@ -1,5 +0,0 @@
-import GridListItem from './grid-list-item.svelte';
-
-export default GridListItem;
-export type { GridListItemProps } from './grid-list-item.types.ts';
-export { GridListItem };