@astronox/core 0.2.0 → 0.2.2

package/src/client/preferences.ts

@@ -0,0 +1,400 @@
+export type PreferenceScalar = boolean | number | string;
+
+export type PreferenceSchema =
+  | { type: 'boolean' }
+  | {
+      type: 'integer';
+      min?: number;
+      max?: number;
+      values?: readonly number[];
+    }
+  | { type: 'number'; min?: number; max?: number }
+  | { type: 'string'; values?: readonly string[] }
+  | {
+      type: 'object';
+      properties: Readonly<Record<string, PreferenceSchema>>;
+    }
+  | { type: 'array'; items: PreferenceSchema };
+
+export type PreferenceMigration = {
+  fromVersion: number;
+  fromKey?: string;
+  rename?: Readonly<Record<string, string>>;
+  defaults?: Readonly<Record<string, unknown>>;
+};
+
+export type PreferenceDefinition<T> = {
+  id: string;
+  key: string;
+  version: number;
+  defaultValue: T;
+  schema: PreferenceSchema;
+  migrations?: readonly PreferenceMigration[];
+};
+
+export type AnyPreferenceDefinition = PreferenceDefinition<unknown>;
+
+export type PreferenceBinding = {
+  id: string;
+  path?: string;
+};
+
+export type PreferenceCondition = PreferenceBinding & {
+  equals: PreferenceScalar;
+};
+
+export type PreferenceNumberBounds = {
+  min: number;
+  max: number;
+  when?: PreferenceCondition;
+};
+
+export type PreferenceRegistry = {
+  get<T>(definition: PreferenceDefinition<T>): T;
+  set<T>(definition: PreferenceDefinition<T>, value: T): void;
+  reset<T>(definition: PreferenceDefinition<T>): void;
+  subscribe<T>(
+    definition: PreferenceDefinition<T>,
+    listener: (value: T) => void,
+  ): () => void;
+  destroy(): void;
+};
+
+export type PreferenceRegistryConfig = {
+  definitions: readonly AnyPreferenceDefinition[];
+};
+
+type PreferenceSnapshot = {
+  values: Record<string, unknown>;
+  rawValues: Record<string, string>;
+};
+
+type PreferenceChangeDetail = {
+  id: string;
+  source: string;
+  value: unknown;
+};
+
+const snapshotGlobalKey = '__astronoxPreferenceSnapshot';
+const preferenceChangeEvent = 'astronox:preference-change';
+let registrySequence = 0;
+
+export function definePreference<T>(
+  definition: PreferenceDefinition<T>,
+): PreferenceDefinition<T> {
+  assertDefinition(definition);
+  if (!matchesPreferenceSchema(definition.defaultValue, definition.schema)) {
+    throw new TypeError(`Invalid default value for preference ${definition.id}`);
+  }
+  return definition;
+}
+
+export function createPreferenceRegistry({
+  definitions,
+}: PreferenceRegistryConfig): PreferenceRegistry {
+  const source = `registry:${++registrySequence}`;
+  const definitionsById = new Map<string, AnyPreferenceDefinition>();
+  const definitionsByStorageKey = new Map<string, AnyPreferenceDefinition>();
+  for (const definition of definitions) {
+    assertDefinition(definition);
+    if (definitionsById.has(definition.id)) {
+      throw new Error(`Duplicate preference definition: ${definition.id}`);
+    }
+    const storageKey = getPreferenceStorageKey(definition);
+    if (definitionsByStorageKey.has(storageKey)) {
+      throw new Error(`Duplicate preference storage key: ${storageKey}`);
+    }
+    definitionsById.set(definition.id, definition);
+    definitionsByStorageKey.set(storageKey, definition);
+  }
+
+  const snapshot = resolveSnapshot(definitions);
+  const listeners = new Map<string, Set<(value: unknown) => void>>();
+
+  const requireDefinition = <T>(
+    definition: PreferenceDefinition<T>,
+  ): PreferenceDefinition<T> => {
+    if (!definitionsById.has(definition.id)) {
+      throw new Error(
+        `Preference ${definition.id} does not belong to this registry`,
+      );
+    }
+    return definition;
+  };
+
+  const notify = (id: string, value: unknown): void => {
+    for (const listener of listeners.get(id) ?? []) listener(value);
+  };
+
+  const apply = (
+    definition: AnyPreferenceDefinition,
+    value: unknown,
+    options: {
+      persist: boolean;
+      announce: boolean;
+      notifyIfEqual?: boolean;
+    },
+  ): void => {
+    if (!matchesPreferenceSchema(value, definition.schema)) return;
+    const raw = JSON.stringify(value);
+    if (snapshot.rawValues[definition.id] === raw) {
+      if (options.notifyIfEqual) {
+        notify(definition.id, structuredCloneValue(value));
+      }
+      return;
+    }
+
+    const cloned = structuredCloneValue(value);
+    snapshot.values[definition.id] = cloned;
+    snapshot.rawValues[definition.id] = raw;
+    syncGlobalSnapshot(definition.id, cloned, raw);
+    if (options.persist) {
+      writeStorage(getPreferenceStorageKey(definition), raw);
+    }
+    notify(definition.id, cloned);
+    if (options.announce) {
+      document.dispatchEvent(
+        new CustomEvent<PreferenceChangeDetail>(preferenceChangeEvent, {
+          detail: { id: definition.id, source, value: cloned },
+        }),
+      );
+    }
+  };
+
+  const handlePreferenceChange = (event: Event): void => {
+    const detail = (event as CustomEvent<PreferenceChangeDetail>).detail;
+    if (detail?.source === source) return;
+    const definition = detail ? definitionsById.get(detail.id) : undefined;
+    if (definition) {
+      apply(definition, detail.value, {
+        persist: false,
+        announce: false,
+        notifyIfEqual: true,
+      });
+    }
+  };
+
+  const handleStorage = (event: StorageEvent): void => {
+    const definition = event.key
+      ? definitionsByStorageKey.get(event.key)
+      : undefined;
+    if (!definition) return;
+    const value = parseStoredValue(event.newValue);
+    if (!matchesPreferenceSchema(value, definition.schema)) return;
+    apply(definition, value, { persist: false, announce: true });
+  };
+
+  document.addEventListener(preferenceChangeEvent, handlePreferenceChange);
+  window.addEventListener('storage', handleStorage);
+
+  return {
+    get<T>(definition: PreferenceDefinition<T>): T {
+      requireDefinition(definition);
+      return structuredCloneValue(snapshot.values[definition.id] as T);
+    },
+    set<T>(definition: PreferenceDefinition<T>, value: T): void {
+      requireDefinition(definition);
+      if (!matchesPreferenceSchema(value, definition.schema)) {
+        throw new TypeError(`Invalid value for preference ${definition.id}`);
+      }
+      apply(definition, value, { persist: true, announce: true });
+    },
+    reset<T>(definition: PreferenceDefinition<T>): void {
+      requireDefinition(definition);
+      apply(definition, definition.defaultValue, {
+        persist: true,
+        announce: true,
+      });
+    },
+    subscribe<T>(
+      definition: PreferenceDefinition<T>,
+      listener: (value: T) => void,
+    ): () => void {
+      requireDefinition(definition);
+      const definitionListeners = listeners.get(definition.id) ?? new Set();
+      const wrapped = (value: unknown): void => listener(value as T);
+      definitionListeners.add(wrapped);
+      listeners.set(definition.id, definitionListeners);
+      return () => {
+        definitionListeners.delete(wrapped);
+        if (definitionListeners.size === 0) listeners.delete(definition.id);
+      };
+    },
+    destroy(): void {
+      document.removeEventListener(preferenceChangeEvent, handlePreferenceChange);
+      window.removeEventListener('storage', handleStorage);
+      listeners.clear();
+    },
+  };
+}
+
+function getPreferenceStorageKey(
+  definition: Pick<AnyPreferenceDefinition, 'key' | 'version'>,
+): string {
+  return `${definition.key}:v${definition.version}`;
+}
+
+function matchesPreferenceSchema(
+  value: unknown,
+  schema: PreferenceSchema,
+): boolean {
+  if (schema.type === 'boolean') return typeof value === 'boolean';
+  if (schema.type === 'string') {
+    return (
+      typeof value === 'string' &&
+      (!schema.values || schema.values.includes(value))
+    );
+  }
+  if (schema.type === 'number' || schema.type === 'integer') {
+    if (
+      typeof value !== 'number' ||
+      !Number.isFinite(value) ||
+      (schema.type === 'integer' && !Number.isInteger(value)) ||
+      (schema.min !== undefined && value < schema.min) ||
+      (schema.max !== undefined && value > schema.max)
+    ) {
+      return false;
+    }
+    return (
+      schema.type !== 'integer' ||
+      !schema.values ||
+      schema.values.includes(value)
+    );
+  }
+  if (schema.type === 'array') {
+    return (
+      Array.isArray(value) &&
+      value.every((item) => matchesPreferenceSchema(item, schema.items))
+    );
+  }
+  if (!isRecord(value)) return false;
+
+  return Object.entries(schema.properties).every(([key, propertySchema]) =>
+    matchesPreferenceSchema(value[key], propertySchema),
+  );
+}
+
+function resolveSnapshot(
+  definitions: readonly AnyPreferenceDefinition[],
+): PreferenceSnapshot {
+  const snapshot = getGlobalSnapshot() ?? { values: {}, rawValues: {} };
+  setGlobalSnapshot(snapshot);
+
+  for (const definition of definitions) {
+    const bootstrapped = snapshot.values[definition.id];
+    if (matchesPreferenceSchema(bootstrapped, definition.schema)) {
+      snapshot.rawValues[definition.id] = JSON.stringify(bootstrapped);
+      continue;
+    }
+
+    const value = readPreference(definition);
+    snapshot.values[definition.id] = value;
+    snapshot.rawValues[definition.id] = JSON.stringify(value);
+  }
+  return snapshot;
+}
+
+function readPreference<T>(definition: PreferenceDefinition<T>): T {
+  const current = parseStoredValue(
+    readStorage(getPreferenceStorageKey(definition)),
+  );
+  if (matchesPreferenceSchema(current, definition.schema)) return current as T;
+
+  for (const migration of [...(definition.migrations ?? [])].toSorted(
+    (left, right) => right.fromVersion - left.fromVersion,
+  )) {
+    const key = `${migration.fromKey ?? definition.key}:v${migration.fromVersion}`;
+    const migrated = applyMigration(
+      parseStoredValue(readStorage(key)),
+      migration,
+    );
+    if (matchesPreferenceSchema(migrated, definition.schema)) {
+      writeStorage(
+        getPreferenceStorageKey(definition),
+        JSON.stringify(migrated),
+      );
+      return migrated as T;
+    }
+  }
+
+  const fallback = structuredCloneValue(definition.defaultValue);
+  writeStorage(getPreferenceStorageKey(definition), JSON.stringify(fallback));
+  return fallback;
+}
+
+function applyMigration(
+  value: unknown,
+  migration: PreferenceMigration,
+): unknown {
+  if (!isRecord(value)) return value;
+  const migrated: Record<string, unknown> = { ...value };
+  for (const [from, to] of Object.entries(migration.rename ?? {})) {
+    if (from in migrated && !(to in migrated)) migrated[to] = migrated[from];
+    delete migrated[from];
+  }
+  for (const [key, fallback] of Object.entries(migration.defaults ?? {})) {
+    if (!(key in migrated)) migrated[key] = fallback;
+  }
+  return migrated;
+}
+
+function getGlobalSnapshot(): PreferenceSnapshot | undefined {
+  return (globalThis as Record<string, unknown>)[snapshotGlobalKey] as
+    | PreferenceSnapshot
+    | undefined;
+}
+
+function setGlobalSnapshot(snapshot: PreferenceSnapshot): void {
+  (globalThis as Record<string, unknown>)[snapshotGlobalKey] = snapshot;
+}
+
+function syncGlobalSnapshot(id: string, value: unknown, raw: string): void {
+  const globalSnapshot = getGlobalSnapshot();
+  if (!globalSnapshot) return;
+  globalSnapshot.values[id] = value;
+  globalSnapshot.rawValues[id] = raw;
+}
+
+function readStorage(key: string): string | null {
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(key: string, value: string): void {
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+    // The in-memory snapshot remains authoritative for this document.
+  }
+}
+
+function parseStoredValue(raw: string | null): unknown {
+  if (raw === null) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+function assertDefinition(definition: AnyPreferenceDefinition): void {
+  if (!definition.id.trim() || !definition.key.trim()) {
+    throw new Error('Preference ids and keys must be non-empty');
+  }
+  if (!Number.isInteger(definition.version) || definition.version < 1) {
+    throw new RangeError('Preference versions must be positive integers');
+  }
+}
+
+function structuredCloneValue<T>(value: T): T {
+  return typeof structuredClone === 'function'
+    ? structuredClone(value)
+    : (JSON.parse(JSON.stringify(value)) as T);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/components/actions/Button/Button.astro

@@ -57,9 +57,21 @@ const resolvedTone = tone ?? dataTone;
       rel={resolvedRel}
       target={target}
     >
-      {hasLeading ? <slot name="leading" /> : null}
+      {
+        hasLeading ? (
+          <span class="nox-button__affix">
+            <slot name="leading" />
+          </span>
+        ) : null
+      }
       <slot />
-      {hasTrailing ? <slot name="trailing" /> : null}
+      {
+        hasTrailing ? (
+          <span class="nox-button__affix">
+            <slot name="trailing" />
+          </span>
+        ) : null
+      }
     </a>
   ) : href ? (
     <span
@@ -74,9 +86,21 @@ const resolvedTone = tone ?? dataTone;
       data-button-size={size}
       data-tone={resolvedTone}
     >
-      {hasLeading ? <slot name="leading" /> : null}
+      {
+        hasLeading ? (
+          <span class="nox-button__affix">
+            <slot name="leading" />
+          </span>
+        ) : null
+      }
       <slot />
-      {hasTrailing ? <slot name="trailing" /> : null}
+      {
+        hasTrailing ? (
+          <span class="nox-button__affix">
+            <slot name="trailing" />
+          </span>
+        ) : null
+      }
     </span>
   ) : (
     <button
@@ -92,9 +116,21 @@ const resolvedTone = tone ?? dataTone;
       disabled={disabled}
       type={type}
     >
-      {hasLeading ? <slot name="leading" /> : null}
+      {
+        hasLeading ? (
+          <span class="nox-button__affix">
+            <slot name="leading" />
+          </span>
+        ) : null
+      }
       <slot />
-      {hasTrailing ? <slot name="trailing" /> : null}
+      {
+        hasTrailing ? (
+          <span class="nox-button__affix">
+            <slot name="trailing" />
+          </span>
+        ) : null
+      }
     </button>
   )
 }

package/src/components/actions/Button/Button.css

@@ -80,6 +80,12 @@
   block-size: 2rem;
 }
 
+.nox-button[data-button-icon-only] > [data-tone] {
+  display: grid;
+  place-items: center;
+  color: var(--nox-tone-color);
+}
+
 .nox-button[data-button-icon-only][data-button-size='sm'] svg {
   inline-size: 1.5rem;
   block-size: 1.5rem;
@@ -90,6 +96,19 @@
   block-size: 2.25rem;
 }
 
+.nox-button__affix {
+  display: grid;
+  inline-size: 1.25rem;
+  block-size: 1.25rem;
+  place-items: center;
+}
+
+.nox-button__affix svg {
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+}
+
 .nox-button[data-button-borderless] {
   border: 0;
   border-radius: 0;

package/src/components/actions/IdentityProviderAction/IdentityProviderAction.astro

@@ -0,0 +1,35 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import type { Tone } from '../../../theme/contracts';
+import Button from '../Button/Button.astro';
+
+type Props = HTMLAttributes<'button'> & {
+  label: string;
+  pendingLabel?: string;
+  tone?: Tone;
+};
+
+const {
+  label,
+  pendingLabel = label,
+  tone,
+  ...attrs
+}: Props = Astro.props;
+---
+
+<Button
+  {...attrs}
+  type="button"
+  prominent
+  tone={tone}
+  data-auth-provider-action
+  data-auth-provider-label={label}
+  data-auth-provider-pending-label={pendingLabel}
+>
+  {
+    Astro.slots.has('leading') ? (
+      <span slot="leading"><slot name="leading" /></span>
+    ) : null
+  }
+  <span data-auth-provider-action-label>{label}</span>
+</Button>

package/src/components/actions/MediaTrigger/MediaTrigger.astro

@@ -4,29 +4,37 @@ import type { DisplayMedia } from '../../../display/contracts';
 import type { Tone } from '../../../theme/contracts';
 import Media from '../../../primitives/media/Media/Media.astro';
 
-type Props = Omit<HTMLAttributes<'button'>, 'type'> & {
+type SharedProps = {
   accentTone?: Tone;
   label: string;
   media: DisplayMedia;
   tone?: Tone;
 };
 
+type Props = SharedProps &
+  Omit<HTMLAttributes<'a'>, 'href' | 'type'> & {
+    href?: string;
+  };
+
 const {
   accentTone,
   class: className,
   'data-tone': dataTone,
+  href,
   label,
   media,
   tone,
   ...attrs
 }: Props = Astro.props;
 const resolvedTone = tone ?? dataTone;
+const Root = href ? 'a' : 'button';
 ---
 
-<button
+<Root
   {...attrs}
   class:list={['media-trigger', className]}
-  type="button"
+  href={href}
+  type={href ? undefined : 'button'}
   aria-label={label}
   data-tone={resolvedTone}
   data-widget="media-trigger"
@@ -52,4 +60,4 @@ const resolvedTone = tone ?? dataTone;
       </span>
     ) : null
   }
-</button>
+</Root>

package/src/components/actions/MediaTrigger/MediaTrigger.css

@@ -12,6 +12,7 @@
   background: transparent;
   color: inherit;
   font: inherit;
+  text-decoration: none;
   cursor: pointer;
   isolation: isolate;
 }

package/src/components/content/CardBody/CardBody.astro

@@ -5,6 +5,7 @@ type Props = HTMLAttributes<'div'> & {
   id?: string;
   inset?: 'default' | 'none';
   overlayBoundary?: boolean;
+  scrollable?: boolean;
 };
 
 const {
@@ -12,6 +13,7 @@ const {
   id,
   inset = 'default',
   overlayBoundary = false,
+  scrollable = false,
   ...attrs
 }: Props = Astro.props;
 ---
@@ -24,6 +26,7 @@ const {
   data-surface
   data-inset={inset}
   data-overlay-boundary={overlayBoundary ? true : undefined}
+  data-scrollable={scrollable ? true : undefined}
 >
   <div class="card-body__content">
     <slot />

package/src/components/content/CardBody/CardBody.css

@@ -41,6 +41,16 @@
   overflow: clip;
 }
 
+.card-body[data-scrollable] {
+  overflow: auto;
+  overscroll-behavior: contain;
+}
+
+.card-body[data-scrollable] .card-body__content {
+  min-block-size: 100%;
+  align-self: flex-start;
+}
+
 .card-body p {
   margin: 0;
 }

package/src/components/content/MarkdownContent/MarkdownContent.css

@@ -211,7 +211,6 @@
 .markdown-content__change-label {
   min-width: 0;
   flex: none;
-  font-weight: var(--nox-font-weight-medium);
   overflow-wrap: anywhere;
 }
 

package/src/components/content/MarkdownContent/MarkdownNode.astro

@@ -112,6 +112,7 @@ const listItems =
     <div class="markdown-content__change">
       <span class="markdown-content__change-label">
         {node.label.map((child) => <MarkdownInline node={child} />)}
+        <span>:</span>
       </span>
       {node.presentation === 'statement' ? (
         <span class="markdown-content__change-values">