npm - @lostgradient/cinder - Versions diffs - 0.6.0 → 0.7.0 - Mend

@lostgradient/cinder 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1827) hide show

package/src/components/capability-gate/capability-gate.svelte ADDED Viewed

@@ -0,0 +1,137 @@
+<script lang="ts" module>
+/** Human-readable default status text per state. */
+const DEFAULT_STATUS_TEXT = {
+    supported: 'Available',
+    unsupported: 'Not supported in this browser',
+    'permission-needed': 'Permission required',
+    'permission-denied': 'Permission was denied',
+    loading: 'Checking availability…',
+    unavailable: 'Not available',
+};
+export {};
+</script>
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import { devWarn } from '../../utilities/dev-warn.ts';
+const KNOWN_STATES = [
+    'supported',
+    'unsupported',
+    'permission-needed',
+    'permission-denied',
+    'loading',
+    'unavailable',
+];
+let { feature,
+// Destructured off `state` to avoid svelte-check treating the bare identifier
+// as the `$state` rune (the public prop name is still `state`).
+state: stateProp, variant = 'inline', primaryAction, onprimaryaction, fallbackAction, fallbackHref, onfallbackaction, dismissAction, ondismiss, children, class: customClassName, ...rest } = $props();
+// Guard the runtime state: a plain-JS or malformed value falls back to
+// `unavailable` (with a dev warning) rather than rendering an unknown
+// data-cinder-state and the raw value as status text.
+const availabilityState = $derived(KNOWN_STATES.includes(stateProp) ? stateProp : 'unavailable');
+$effect(() => {
+    if (!KNOWN_STATES.includes(stateProp)) {
+        devWarn(`CapabilityGate: unknown state "${String(stateProp)}". Expected one of ${KNOWN_STATES.join(', ')}. Falling back to "unavailable".`);
+    }
+});
+let visible = $state(true);
+let dismissButton = $state();
+// Re-show the gate when the situation changes (e.g. permission-needed →
+// permission-denied), so a previous dismissal doesn't permanently hide a new,
+// possibly more urgent state. Reads feature + stateProp to track them.
+$effect(() => {
+    void feature;
+    void stateProp;
+    visible = true;
+});
+const statusText = $derived(DEFAULT_STATUS_TEXT[availabilityState] ?? availabilityState);
+const isLoading = $derived(availabilityState === 'loading');
+const isError = $derived(availabilityState === 'permission-denied' || availabilityState === 'unsupported');
+const isWarning = $derived(availabilityState === 'permission-needed');
+const isSuccess = $derived(availabilityState === 'supported');
+const resolvedVariant = $derived(isError ? 'error' : isWarning ? 'warning' : isSuccess ? 'success' : 'info');
+function handleDismiss() {
+    // Blur the dismiss button before it unmounts so focus moves to <body>
+    // predictably rather than being stranded on a detached node. The consumer
+    // owns where focus should land next (e.g. a trigger to re-open the gate) and
+    // can set it in `ondismiss` — the component cannot know the right target.
+    dismissButton?.blur();
+    visible = false;
+    ondismiss?.();
+}
+</script>
+{#if visible}
+  <div
+    {...rest}
+    class={classNames('cinder-capability-gate', customClassName)}
+    data-cinder-state={availabilityState}
+    data-cinder-variant={resolvedVariant}
+    data-cinder-presentation={variant}
+  >
+    <!-- Status text announced to assistive technology. aria-busy lives on the
+         live region so a loading→ready transition is announced consistently. -->
+    <div
+      class="cinder-capability-gate__status"
+      role="status"
+      aria-live="polite"
+      aria-busy={isLoading ? 'true' : undefined}
+    >
+      <span class="cinder-capability-gate__feature">{feature}</span>
+      <span class="cinder-capability-gate__state-text">{statusText}</span>
+    </div>
+    {#if children}
+      <div class="cinder-capability-gate__content">
+        {@render children()}
+      </div>
+    {/if}
+    {#if primaryAction || fallbackAction || fallbackHref || dismissAction}
+      <div class="cinder-capability-gate__actions">
+        {#if primaryAction}
+          <button
+            type="button"
+            class="cinder-capability-gate__primary"
+            onclick={onprimaryaction}
+            aria-label="{primaryAction} for {feature}"
+          >
+            {primaryAction}
+          </button>
+        {/if}
+        {#if fallbackHref}
+          <a
+            href={fallbackHref}
+            class="cinder-capability-gate__fallback"
+            aria-label="{fallbackAction ?? 'Alternative option'} for {feature}"
+          >
+            {fallbackAction ?? 'Alternative option'}
+          </a>
+        {:else if fallbackAction}
+          <button
+            type="button"
+            class="cinder-capability-gate__fallback"
+            onclick={onfallbackaction}
+            aria-label="{fallbackAction} for {feature}"
+          >
+            {fallbackAction}
+          </button>
+        {/if}
+        {#if dismissAction}
+          <button
+            bind:this={dismissButton}
+            type="button"
+            class="cinder-capability-gate__dismiss"
+            onclick={handleDismiss}
+            aria-label={dismissAction}
+          >
+            {dismissAction}
+          </button>
+        {/if}
+      </div>
+    {/if}
+  </div>
+{/if}

package/src/components/capability-gate/capability-gate.types.ts ADDED Viewed

@@ -0,0 +1,83 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+/** Availability state for a browser feature or permission. */
+export type CapabilityGateState =
+  | 'supported'
+  | 'unsupported'
+  | 'permission-needed'
+  | 'permission-denied'
+  | 'loading'
+  | 'unavailable';
+/** Presentation style for the gate. */
+export type CapabilityGateVariant = 'inline' | 'banner' | 'callout';
+/** Props for the CapabilityGate component. */
+export type CapabilityGateProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'class' | 'children' | 'role'
+> & {
+  /** The feature being gated (used in accessible status text). */
+  feature: string;
+  /** Current availability state. */
+  state: CapabilityGateState;
+  /** Presentation variant. @default "inline" */
+  variant?: CapabilityGateVariant;
+  /** Label for the primary action button (e.g. "Allow access", "Enable notifications"). */
+  primaryAction?: string;
+  /** Called when the user clicks the primary action button. */
+  onprimaryaction?: () => void;
+  /** Label for the fallback action (e.g. "Use a different method"). */
+  fallbackAction?: string;
+  /** Href for a fallback link (renders an anchor instead of a button). */
+  fallbackHref?: string;
+  /** Called when the user clicks the fallback action (only when no fallbackHref). */
+  onfallbackaction?: () => void;
+  /** Label for the dismiss action. When provided a dismiss button is rendered. */
+  dismissAction?: string;
+  /**
+   * Called when the user dismisses the gate. The gate unmounts itself on
+   * dismiss; move focus to a sensible target here (e.g. the control that
+   * re-opens the gate) — the component blurs the dismiss button first so focus
+   * is not stranded, but only the consumer knows the right next focus target.
+   */
+  ondismiss?: () => void;
+  /** Custom content rendered below the status text and before the actions. */
+  children?: Snippet;
+  /** Additional class names merged with `.cinder-capability-gate`. */
+  class?: string;
+};
+/**
+ * Cinder-specific props for CapabilityGate, used by the schema generator.
+ */
+export interface CapabilityGateSchemaProps {
+  /** The feature being gated. */
+  feature: string;
+  /** Current availability state. */
+  state: CapabilityGateState;
+  /**
+   * Presentation variant.
+   * @default "inline"
+   */
+  variant?: CapabilityGateVariant;
+  /** Label for the primary action button. */
+  primaryAction?: string;
+  /** Label for the fallback action. */
+  fallbackAction?: string;
+  /** Href for a fallback link. */
+  fallbackHref?: string;
+  /** Label for the dismiss action. */
+  dismissAction?: string;
+  /** Additional class names merged with `.cinder-capability-gate`. */
+  class?: string;
+  /** Called when the primary action button is activated. */
+  onprimaryaction?: () => void;
+  /** Called when the fallback action button is activated. */
+  onfallbackaction?: () => void;
+  /** Called when the gate is dismissed. */
+  ondismiss?: () => void;
+  /** Custom content rendered below the status text and before the actions. */
+  children?: Snippet;
+}

package/src/components/capability-gate/capability-gate.variables.ts ADDED Viewed

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+export default variables;

package/src/components/capability-gate/index.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import './capability-gate.css';
+import CapabilityGate from './capability-gate.svelte';
+export default CapabilityGate;
+export type {
+  CapabilityGateProps,
+  CapabilityGateState,
+  CapabilityGateVariant,
+} from './capability-gate.types.ts';
+export { CapabilityGate };

package/src/components/card/card.schema.ts ADDED Viewed

@@ -0,0 +1,71 @@
+import type { ComponentSchema } from '../../schema-types';
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    title: {
+      type: 'string',
+      description: "Primary heading text rendered inside the card's header region.",
+    },
+    variant: {
+      enum: ['card', 'well'],
+      description: 'Visual container style. `card` is raised; `well` is flatter and inset.',
+    },
+    tone: {
+      enum: ['default', 'danger'],
+      description:
+        'Container risk treatment. `danger` renders a danger-zone surface for high-risk settings or destructive actions.',
+    },
+    bodyTone: {
+      enum: ['default', 'muted'],
+      description: 'Body surface treatment. `muted` renders a grey/inset body region.',
+    },
+    footerTone: {
+      enum: ['default', 'muted'],
+      description: 'Footer surface treatment. `muted` renders a grey/inset footer region.',
+    },
+    edgeToEdgeOnMobile: {
+      type: 'boolean',
+      description: 'Remove side borders/radius and bleed to the viewport edge on narrow screens.',
+    },
+    padding: {
+      enum: ['none', 'default'],
+      description:
+        'Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image).',
+    },
+    headingLevel: {
+      enum: [2, 3, 4, 5, 6],
+      description:
+        'Heading level for the generated title. Defaults to `3`. Set this so the\ncard title nests correctly within the surrounding document outline.',
+    },
+    description: {
+      type: 'string',
+      description: 'Optional subheading rendered as a paragraph below the title inside the header.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+      },
+      {
+        name: 'class',
+        reason: 'unknown-shape',
+      },
+      {
+        name: 'footer',
+        reason: 'function-or-snippet',
+      },
+      {
+        name: 'header',
+        reason: 'function-or-snippet',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+export default schema as ComponentSchema;

package/src/components/card/card.svelte ADDED Viewed

@@ -0,0 +1,73 @@
+<script lang="ts" module>
+export {};
+</script>
+<script lang="ts">
+import CircleAlert from 'lucide-svelte/icons/circle-alert';
+import { composeDescribedBy } from '../../_internal/field-control.ts';
+import { classNames } from '../../utilities/class-names.ts';
+const generatedId = $props.id();
+let { class: className, children, header, title, headingLevel = 3, description, footer, variant = 'card', tone = 'default', bodyTone = 'default', footerTone = 'default', edgeToEdgeOnMobile = false, padding = 'default', ...rest } = $props();
+// Coerce + clamp at runtime: a consumer can pass 0, 7, NaN, or a non-numeric
+// value (JS callers, schema-driven usage). Building `h${headingLevel}` directly
+// would emit invalid markup like <h0>/<hNaN>. Matches EmptyState's heading clamp.
+const resolvedHeadingLevel = $derived(Number.isFinite(Math.trunc(Number(headingLevel)))
+    ? Math.min(6, Math.max(1, Math.trunc(Number(headingLevel))))
+    : 3);
+const titleTag = $derived(`h${resolvedHeadingLevel}`);
+const hasGeneratedHeader = $derived(Boolean(title && !header));
+const titleId = $derived(hasGeneratedHeader ? `${generatedId}-title` : undefined);
+const descriptionId = $derived(hasGeneratedHeader && description ? `${generatedId}-description` : undefined);
+const hasExternalRole = $derived(typeof rest.role === 'string' && rest.role.trim().length > 0);
+const hasExternalLabel = $derived((typeof rest['aria-labelledby'] === 'string' && rest['aria-labelledby'].trim().length > 0) ||
+    (typeof rest['aria-label'] === 'string' && rest['aria-label'].trim().length > 0));
+const describedBy = $derived(composeDescribedBy(descriptionId, rest['aria-describedby']));
+const labelAttributes = $derived(hasGeneratedHeader
+    ? {
+        ...(!hasExternalRole ? { role: 'group' } : {}),
+        ...(!hasExternalLabel ? { 'aria-labelledby': titleId } : {}),
+        ...(describedBy ? { 'aria-describedby': describedBy } : {}),
+    }
+    : {});
+</script>
+<div
+  {...rest}
+  class={classNames('cinder-card', className)}
+  data-cinder-variant={variant}
+  data-cinder-tone={tone}
+  data-cinder-edge-to-edge-mobile={edgeToEdgeOnMobile ? '' : undefined}
+  {...labelAttributes}
+>
+  {#if header}
+    <div class="cinder-card__header">
+      {@render header()}
+    </div>
+  {:else if title}
+    <div class="cinder-card__header">
+      <div class="cinder-card__title-row">
+        {#if tone === 'danger'}
+          <span class="cinder-card__risk-icon" aria-hidden="true">
+            <CircleAlert size={18} strokeWidth={2.25} />
+          </span>
+        {/if}
+        <svelte:element this={titleTag} id={titleId} class="cinder-card__title"
+          >{title}</svelte:element
+        >
+      </div>
+      {#if description}
+        <p id={descriptionId} class="cinder-card__description">{description}</p>
+      {/if}
+    </div>
+  {/if}
+  <div class="cinder-card__body" data-cinder-tone={bodyTone} data-cinder-padding={padding}>
+    {@render children()}
+  </div>
+  {#if footer}
+    <div class="cinder-card__footer" data-cinder-tone={footerTone}>
+      {@render footer()}
+    </div>
+  {/if}
+</div>

package/src/components/card/card.types.ts ADDED Viewed

@@ -0,0 +1,58 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+export type CardVariant = 'card' | 'well';
+export type CardTone = 'default' | 'muted';
+export type CardSurfaceTone = 'default' | 'danger';
+/** Controls body padding. `none` removes all padding for flush/full-bleed content. Future values like `compact` may be added. */
+export type CardPadding = 'default' | 'none';
+/** Heading level for the generated card title, so the document outline stays correct. */
+export type CardHeadingLevel = 2 | 3 | 4 | 5 | 6;
+type CardBase = HTMLAttributes<HTMLDivElement> & {
+  class?: string;
+  /** Visual container style. `card` is raised; `well` is flatter and inset. */
+  variant?: CardVariant;
+  /** Container risk treatment. `danger` renders a danger-zone surface for high-risk settings or destructive actions. */
+  tone?: CardSurfaceTone;
+  /** Body surface treatment. `muted` renders a grey/inset body region. */
+  bodyTone?: CardTone;
+  /** Footer surface treatment. `muted` renders a grey/inset footer region. */
+  footerTone?: CardTone;
+  /** Remove side borders/radius and bleed to the viewport edge on narrow screens. */
+  edgeToEdgeOnMobile?: boolean;
+  /** Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image). */
+  padding?: CardPadding;
+};
+/** Basic card with no generated header. */
+type CardPlain = CardBase & {
+  children: Snippet;
+  footer?: Snippet;
+  header?: never;
+  title?: never;
+  headingLevel?: never;
+  description?: never;
+};
+/** Card with a custom header snippet — full control over header content. */
+type CardWithHeader = CardBase & {
+  header: Snippet;
+  children: Snippet;
+  footer?: Snippet;
+  title?: never;
+  headingLevel?: never;
+  description?: never;
+};
+/** Card with a title/description string API — simpler for standard cards. */
+type CardWithTitle = CardBase & {
+  /** Primary heading text rendered inside the card's header region. */
+  title: string;
+  /**
+   * Heading level for the generated title. Defaults to `3`. Set this so the
+   * card title nests correctly within the surrounding document outline.
+   */
+  headingLevel?: CardHeadingLevel;
+  /** Optional subheading rendered as a paragraph below the title inside the header. */
+  description?: string;
+  children: Snippet;
+  footer?: Snippet;
+  header?: never;
+};
+export type CardProps = CardPlain | CardWithHeader | CardWithTitle;

package/src/components/card/card.variables.ts ADDED Viewed

@@ -0,0 +1,3 @@
+const variables: readonly string[] = ['--cinder-card-mobile-bleed'];
+export default variables;

package/src/components/card/index.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import './card.css';
+import Card from './card.svelte';
+export default Card;
+export type {
+  CardPadding,
+  CardProps,
+  CardSurfaceTone,
+  CardTone,
+  CardVariant,
+} from './card.types.ts';
+export { Card };

package/src/components/carousel/carousel.schema.ts ADDED Viewed

@@ -0,0 +1,50 @@
+import type { ComponentSchema } from '../../schema-types';
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    activeIndex: {
+      type: 'number',
+      description: 'Zero-based active index (bindable).',
+    },
+    autoplay: {
+      type: 'boolean',
+      description: 'Enables interval-based auto-advance.',
+    },
+    autoplayInterval: {
+      type: 'number',
+      description: 'Milliseconds between auto-advance ticks.',
+    },
+    label: {
+      type: 'string',
+      description: 'Accessible name for the carousel region.',
+    },
+    description: {
+      type: 'string',
+      description: 'Optional accessible description linked to the region.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional classes merged onto the root element.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'controlLabels',
+        reason: 'unknown-shape',
+        description: 'Override labels for controls and picker.',
+      },
+      {
+        name: 'slides',
+        reason: 'unknown-shape',
+        required: true,
+        description: 'Ordered list of slides.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+export default schema as ComponentSchema;