@astronox/core 0.2.1 → 0.2.3

package/src/client/formSubmission.ts

@@ -0,0 +1,177 @@
+export type FormSubmissionMode = 'create' | 'edit';
+
+export type FormSubmissionState = {
+  dirty: boolean;
+  pending: boolean;
+};
+
+export type FormSubmissionResult<TValue> = {
+  status: 'saved' | 'unchanged';
+  value: TValue;
+};
+
+export type FormSubmissionControllerConfig<TValue> = {
+  form: HTMLFormElement;
+  mode: FormSubmissionMode;
+  readValue(): TValue;
+  save(value: TValue): Promise<void>;
+  onSuccess(result: FormSubmissionResult<TValue>): void | Promise<void>;
+  onError?(reason: unknown): void;
+  onStateChange?(state: FormSubmissionState): void;
+  changeEvents?: readonly string[];
+  equals?(left: TValue, right: TValue): boolean;
+};
+
+export type FormSubmissionController = {
+  destroy(): void;
+  refresh(): void;
+};
+
+const defaultChangeEvents = ['input', 'change'] as const;
+
+export function createFormSubmissionController<TValue>({
+  form,
+  mode,
+  readValue,
+  save,
+  onSuccess,
+  onError,
+  onStateChange,
+  changeEvents = defaultChangeEvents,
+  equals = areStructurallyEqual,
+}: FormSubmissionControllerConfig<TValue>): FormSubmissionController {
+  let baseline!: TValue;
+  if (mode === 'edit') baseline = readValue();
+  let dirty = mode === 'create';
+  let pending = false;
+  let destroyed = false;
+
+  const publishState = (): void => {
+    onStateChange?.({ dirty, pending });
+  };
+
+  const refresh = (): void => {
+    if (destroyed || pending) return;
+
+    let nextDirty = true;
+    if (mode === 'edit') {
+      try {
+        nextDirty = !equals(baseline, readValue());
+      } catch {
+        // An incomplete value is still a change; native validation owns errors.
+      }
+    }
+
+    if (nextDirty === dirty) return;
+    dirty = nextDirty;
+    publishState();
+  };
+
+  const handleChange = (): void => refresh();
+
+  const handleSubmit = async (event: SubmitEvent): Promise<void> => {
+    event.preventDefault();
+    if (pending || !form.reportValidity()) return;
+
+    let value: TValue;
+    try {
+      value = readValue();
+    } catch (reason) {
+      onError?.(reason);
+      return;
+    }
+
+    if (mode === 'edit' && equals(baseline, value)) {
+      await onSuccess({ status: 'unchanged', value });
+      return;
+    }
+
+    pending = true;
+    publishState();
+
+    try {
+      await save(value);
+      baseline = value;
+      dirty = false;
+      pending = false;
+      publishState();
+      await onSuccess({ status: 'saved', value });
+    } catch (reason) {
+      pending = false;
+      refresh();
+      publishState();
+      onError?.(reason);
+    }
+  };
+
+  for (const eventName of new Set(changeEvents)) {
+    form.addEventListener(eventName, handleChange);
+  }
+  form.addEventListener('submit', handleSubmit);
+  publishState();
+
+  return {
+    destroy(): void {
+      if (destroyed) return;
+      destroyed = true;
+      for (const eventName of new Set(changeEvents)) {
+        form.removeEventListener(eventName, handleChange);
+      }
+      form.removeEventListener('submit', handleSubmit);
+    },
+    refresh,
+  };
+}
+
+function areStructurallyEqual<TValue>(left: TValue, right: TValue): boolean {
+  return compareValues(left, right, new WeakMap<object, object>());
+}
+
+function compareValues(
+  left: unknown,
+  right: unknown,
+  visited: WeakMap<object, object>,
+): boolean {
+  if (Object.is(left, right)) return true;
+  if (left instanceof Date || right instanceof Date) {
+    return (
+      left instanceof Date &&
+      right instanceof Date &&
+      left.getTime() === right.getTime()
+    );
+  }
+  if (!left || !right || typeof left !== 'object' || typeof right !== 'object') {
+    return false;
+  }
+
+  const knownRight = visited.get(left);
+  if (knownRight) return knownRight === right;
+  visited.set(left, right);
+
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right)) return false;
+    return (
+      left.length === right.length &&
+      left.every((value, index) => compareValues(value, right[index], visited))
+    );
+  }
+
+  const leftPrototype = Object.getPrototypeOf(left);
+  const rightPrototype = Object.getPrototypeOf(right);
+  if (leftPrototype !== rightPrototype) return false;
+
+  const leftKeys = Object.keys(left).sort();
+  const rightKeys = Object.keys(right).sort();
+  if (
+    leftKeys.length !== rightKeys.length ||
+    leftKeys.some((key, index) => key !== rightKeys[index])
+  ) {
+    return false;
+  }
+
+  const leftRecord = left as Record<string, unknown>;
+  const rightRecord = right as Record<string, unknown>;
+  return leftKeys.every((key) =>
+    compareValues(leftRecord[key], rightRecord[key], visited),
+  );
+}

package/src/client/index.ts

@@ -1,3 +1,7 @@
 export * from './clipboard';
 export * from './focus';
+export * from './formSubmission';
+export * from './preferences';
 export * from './scroll';
+export * from '../components/content/MarkdownContent/markdownContentRenderer';
+export * from '../patterns/Table/tableClientController';

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;