@astronox/core 0.2.1 → 0.2.2

package/src/components/feedback/PreferenceBootstrap/PreferenceBootstrap.astro

@@ -0,0 +1,403 @@
+---
+import type { AnyPreferenceDefinition } from '../../../client/preferences';
+
+type Props = {
+  definitions?: readonly AnyPreferenceDefinition[];
+};
+
+const { definitions = [] }: Props = Astro.props;
+const payload = definitions.map((definition) => ({
+  id: definition.id,
+  key: definition.key,
+  version: definition.version,
+  defaultValue: definition.defaultValue,
+  schema: definition.schema,
+  migrations: definition.migrations ?? [],
+}));
+---
+
+<script is:inline define:vars={{ definitions: payload }}>
+  (() => {
+    if (definitions.length === 0) return;
+
+    const globalKey = '__astronoxPreferenceSnapshot';
+    const changeEvent = 'astronox:preference-change';
+    const changeSource = 'bootstrap';
+    const definitionMap = new Map(
+      definitions.map((definition) => [definition.id, definition]),
+    );
+    const clone = (value) =>
+      typeof structuredClone === 'function'
+        ? structuredClone(value)
+        : JSON.parse(JSON.stringify(value));
+    const isRecord = (value) =>
+      typeof value === 'object' && value !== null && !Array.isArray(value);
+    const matches = (value, schema) => {
+      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) => matches(item, schema.items))
+        );
+      }
+      return (
+        isRecord(value) &&
+        Object.entries(schema.properties).every(([key, propertySchema]) =>
+          matches(value[key], propertySchema),
+        )
+      );
+    };
+    const parse = (raw) => {
+      if (raw === null) return undefined;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return undefined;
+      }
+    };
+    const read = (key) => {
+      try {
+        return window.localStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    };
+    const write = (key, value) => {
+      try {
+        window.localStorage.setItem(key, JSON.stringify(value));
+      } catch {
+        // The document-scoped snapshot remains usable without storage.
+      }
+    };
+    const storageKey = (definition, version = definition.version, key) =>
+      `${key ?? definition.key}:v${version}`;
+    const migrate = (value, migration) => {
+      if (!isRecord(value)) return value;
+      const next = { ...value };
+      for (const [from, to] of Object.entries(migration.rename ?? {})) {
+        if (from in next && !(to in next)) next[to] = next[from];
+        delete next[from];
+      }
+      for (const [key, fallback] of Object.entries(
+        migration.defaults ?? {},
+      )) {
+        if (!(key in next)) next[key] = fallback;
+      }
+      return next;
+    };
+    const resolveDefinition = (definition) => {
+      const current = parse(read(storageKey(definition)));
+      if (matches(current, definition.schema)) return current;
+
+      const migrations = [...definition.migrations].sort(
+        (left, right) => right.fromVersion - left.fromVersion,
+      );
+      for (const migration of migrations) {
+        const previous = parse(
+          read(
+            storageKey(
+              definition,
+              migration.fromVersion,
+              migration.fromKey,
+            ),
+          ),
+        );
+        const migrated = migrate(previous, migration);
+        if (matches(migrated, definition.schema)) {
+          write(storageKey(definition), migrated);
+          return migrated;
+        }
+      }
+
+      const fallback = clone(definition.defaultValue);
+      write(storageKey(definition), fallback);
+      return fallback;
+    };
+
+    const previousSnapshot = window[globalKey];
+    const snapshot = {
+      values: isRecord(previousSnapshot?.values)
+        ? previousSnapshot.values
+        : {},
+      rawValues: isRecord(previousSnapshot?.rawValues)
+        ? previousSnapshot.rawValues
+        : {},
+    };
+    for (const definition of definitions) {
+      const value = resolveDefinition(definition);
+      snapshot.values[definition.id] = value;
+      snapshot.rawValues[definition.id] = JSON.stringify(value);
+    }
+    window[globalKey] = snapshot;
+
+    const resolvePath = (binding) => {
+      let value = snapshot.values[binding.id];
+      for (const segment of (binding.path ?? '').split('.').filter(Boolean)) {
+        if (!isRecord(value) || !(segment in value)) return undefined;
+        value = value[segment];
+      }
+      return value;
+    };
+    const parseBinding = (element) => {
+      const id = element.dataset.preferenceId;
+      if (!id || !definitionMap.has(id)) return null;
+      return { id, path: element.dataset.preferencePath };
+    };
+    const resolveConditionalBounds = (element) => {
+      const raw = element.dataset.preferenceNumberBounds;
+      if (!raw) return null;
+      try {
+        const bounds = JSON.parse(raw);
+        if (!bounds.when) return bounds;
+        return Object.is(resolvePath(bounds.when), bounds.when.equals)
+          ? bounds
+          : null;
+      } catch {
+        return null;
+      }
+    };
+    const normalizeNumber = (root, requestedValue) => {
+      root.dataset.preferenceBaseMin ??= root.dataset.comboboxNumberMin ?? '';
+      root.dataset.preferenceBaseMax ??= root.dataset.comboboxNumberMax ?? '';
+      const override = resolveConditionalBounds(root);
+      const min = override?.min ?? Number(root.dataset.preferenceBaseMin);
+      const max = override?.max ?? Number(root.dataset.preferenceBaseMax);
+      const step = Number(root.dataset.comboboxNumberStep) || 1;
+      if (!Number.isFinite(min) || !Number.isFinite(max)) return;
+
+      const options = [...root.querySelectorAll('[data-combobox-option]')];
+      const available = options
+        .map((option) => Number(option.dataset.comboboxOption))
+        .filter((value) => Number.isFinite(value) && value >= min && value <= max)
+        .sort((left, right) => left - right);
+      const bounded = Math.min(max, Math.max(min, Number(requestedValue)));
+      const value =
+        available.length > 0
+          ? available.reduce((closest, candidate) =>
+              Math.abs(candidate - bounded) < Math.abs(closest - bounded)
+                ? candidate
+                : closest,
+            )
+          : Math.min(
+              max,
+              Math.max(
+                min,
+                min + Math.round((bounded - min) / step) * step,
+              ),
+            );
+
+      root.dataset.comboboxNumberMin = String(min);
+      root.dataset.comboboxNumberMax = String(max);
+      for (const option of options) {
+        const optionValue = Number(option.dataset.comboboxOption);
+        option.hidden = optionValue < min || optionValue > max;
+        option.setAttribute('aria-selected', String(optionValue === value));
+      }
+      const input = root.querySelector('[data-combobox-number-input]');
+      if (input instanceof HTMLInputElement) {
+        input.value = String(value);
+        input.setAttribute('aria-valuemin', String(min));
+        input.setAttribute('aria-valuemax', String(max));
+        input.setAttribute('aria-valuenow', String(value));
+      }
+      const decrement = root.querySelector(
+        '[data-combobox-number-step="decrement"]',
+      );
+      const increment = root.querySelector(
+        '[data-combobox-number-step="increment"]',
+      );
+      if (decrement instanceof HTMLButtonElement) decrement.disabled = value <= min;
+      if (increment instanceof HTMLButtonElement) increment.disabled = value >= max;
+    };
+    const applyOptions = (root, requestedValue) => {
+      const requested = Array.isArray(requestedValue)
+        ? requestedValue.map(String)
+        : requestedValue === undefined
+          ? []
+          : [String(requestedValue)];
+      const selected = new Set(requested);
+      for (const option of root.querySelectorAll('[data-combobox-option]')) {
+        option.setAttribute(
+          'aria-selected',
+          String(selected.has(option.dataset.comboboxOption ?? '')),
+        );
+      }
+      const valuesRoot = root.querySelector('[data-combobox-values]');
+      const placeholder = root.querySelector('[data-combobox-placeholder]');
+      if (
+        !(valuesRoot instanceof HTMLElement) ||
+        !(placeholder instanceof HTMLElement)
+      ) {
+        return;
+      }
+      for (const tag of valuesRoot.querySelectorAll('[data-combobox-tag]')) {
+        tag.remove();
+      }
+      for (const value of requested) {
+        const template = [
+          ...root.querySelectorAll('template[data-combobox-tag-template]'),
+        ].find((candidate) => candidate.dataset.comboboxTagTemplate === value);
+        const tag = template?.content.firstElementChild?.cloneNode(true);
+        if (tag) valuesRoot.insertBefore(tag, placeholder);
+      }
+      placeholder.hidden = requested.length > 0;
+    };
+    const applyBinding = (element) => {
+      if (!(element instanceof HTMLElement)) return;
+      const binding = parseBinding(element);
+      if (!binding) return;
+      const value = resolvePath(binding);
+      const control = element.dataset.preferenceControl;
+
+      if (control === 'checkbox') {
+        const input = element.querySelector('input[type="checkbox"]');
+        if (input instanceof HTMLInputElement && typeof value === 'boolean') {
+          input.checked = value;
+        }
+      } else if (control === 'text') {
+        const input = element.querySelector('[data-text-input-control]');
+        if (input instanceof HTMLInputElement && typeof value === 'string') {
+          input.value = value;
+        }
+      } else if (control === 'combobox-number' && typeof value === 'number') {
+        normalizeNumber(element, value);
+      } else if (control === 'combobox-options') {
+        applyOptions(element, value);
+      }
+    };
+    const applyBindings = (root) => {
+      if (root instanceof HTMLElement && root.matches('[data-preference-id]')) {
+        applyBinding(root);
+      }
+      for (const element of root.querySelectorAll?.('[data-preference-id]') ?? []) {
+        applyBinding(element);
+      }
+    };
+    const setPath = (binding, value) => {
+      const definition = definitionMap.get(binding.id);
+      if (!definition) return;
+      let next = snapshot.values[binding.id];
+      const path = (binding.path ?? '').split('.').filter(Boolean);
+      if (path.length === 0) {
+        next = value;
+      } else {
+        next = isRecord(next) ? clone(next) : {};
+        let cursor = next;
+        for (const segment of path.slice(0, -1)) {
+          cursor[segment] = isRecord(cursor[segment])
+            ? { ...cursor[segment] }
+            : {};
+          cursor = cursor[segment];
+        }
+        cursor[path[path.length - 1]] = value;
+      }
+      if (!matches(next, definition.schema)) return;
+
+      const raw = JSON.stringify(next);
+      if (snapshot.rawValues[binding.id] === raw) return;
+      snapshot.values[binding.id] = next;
+      snapshot.rawValues[binding.id] = raw;
+      write(storageKey(definition), next);
+      document.dispatchEvent(
+        new CustomEvent(changeEvent, {
+          detail: { id: binding.id, source: changeSource, value: next },
+        }),
+      );
+    };
+    const handleChange = (event) => {
+      const target = event.target;
+      if (!(target instanceof HTMLInputElement)) return;
+      const root = target.closest('[data-preference-id]');
+      if (!(root instanceof HTMLElement)) return;
+      const binding = parseBinding(root);
+      if (!binding) return;
+      if (root.dataset.preferenceControl === 'checkbox') {
+        setPath(binding, target.checked);
+      } else if (root.dataset.preferenceControl === 'text') {
+        setPath(binding, target.value);
+      }
+    };
+    const handleComboboxChange = (event) => {
+      const root = event.target;
+      if (!(root instanceof HTMLElement)) return;
+      const binding = parseBinding(root);
+      if (!binding) return;
+      const detail = event.detail;
+      setPath(
+        binding,
+        detail?.mode === 'number'
+          ? detail.value
+          : root.dataset.comboboxSelectionMode === 'multiple'
+            ? detail?.values ?? []
+            : detail?.values?.[0] ?? '',
+      );
+    };
+    const handlePreferenceChange = (event) => {
+      const detail = event.detail;
+      const definition = detail ? definitionMap.get(detail.id) : undefined;
+      if (!definition || !matches(detail.value, definition.schema)) return;
+      snapshot.values[detail.id] = detail.value;
+      snapshot.rawValues[detail.id] = JSON.stringify(detail.value);
+      applyBindings(document.documentElement);
+    };
+    const handleStorage = (event) => {
+      const definition = definitions.find(
+        (candidate) => storageKey(candidate) === event.key,
+      );
+      if (!definition) return;
+      const value = parse(event.newValue);
+      if (!matches(value, definition.schema)) return;
+      const raw = JSON.stringify(value);
+      if (snapshot.rawValues[definition.id] === raw) return;
+      snapshot.values[definition.id] = value;
+      snapshot.rawValues[definition.id] = raw;
+      document.dispatchEvent(
+        new CustomEvent(changeEvent, {
+          detail: { id: definition.id, source: changeSource, value },
+        }),
+      );
+    };
+
+    const observer = new MutationObserver((records) => {
+      for (const record of records) {
+        for (const node of record.addedNodes) applyBindings(node);
+      }
+    });
+    observer.observe(document.documentElement, { childList: true, subtree: true });
+    document.addEventListener('change', handleChange, true);
+    document.addEventListener('combobox:change', handleComboboxChange);
+    document.addEventListener(changeEvent, handlePreferenceChange);
+    window.addEventListener('storage', handleStorage);
+    applyBindings(document.documentElement);
+    document.addEventListener(
+      'DOMContentLoaded',
+      () => {
+        applyBindings(document.documentElement);
+        observer.disconnect();
+      },
+      { once: true },
+    );
+  })();
+</script>

package/src/components/forms/Checkbox/Checkbox.astro

@@ -1,5 +1,6 @@
 ---
 import type { HTMLAttributes } from 'astro/types';
+import type { PreferenceBinding } from '../../../client/preferences';
 import type { Tone } from '../../../theme/contracts';
 import CheckIcon from '../../icons/CheckIcon.astro';
 import CloseIcon from '../../icons/CloseIcon.astro';
@@ -9,6 +10,7 @@ type Props = Omit<HTMLAttributes<'input'>, 'class' | 'id' | 'type'> & {
   label: string;
   class?: string;
   invalid?: boolean;
+  preference?: PreferenceBinding;
   tone?: Tone;
 };
 
@@ -20,6 +22,7 @@ const {
   id,
   invalid = false,
   label,
+  preference,
   tone,
   ...attrs
 }: Props = Astro.props;
@@ -35,6 +38,9 @@ const resolvedTone = tone ?? dataTone;
   data-invalid={resolvedInvalid ? true : undefined}
   data-tone={resolvedTone}
   data-widget="checkbox"
+  data-preference-id={preference?.id}
+  data-preference-path={preference?.path}
+  data-preference-control={preference ? 'checkbox' : undefined}
 >
   <input
     {...attrs}

package/src/components/forms/ChoiceGroup/ChoiceGroup.astro

@@ -0,0 +1,57 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import type { ChoiceOption } from './contracts';
+
+type Props = Omit<HTMLAttributes<'fieldset'>, 'name'> & {
+  label: string;
+  name: string;
+  options: readonly [ChoiceOption, ...ChoiceOption[]];
+  required?: boolean;
+  value?: string;
+};
+
+const {
+  class: className,
+  disabled = false,
+  label,
+  name,
+  options,
+  required = false,
+  value,
+  ...attrs
+}: Props = Astro.props;
+---
+
+<fieldset
+  {...attrs}
+  class:list={['choice-group', className]}
+  data-widget="choice-group"
+  disabled={disabled}
+>
+  <legend class="choice-group__legend">{label}</legend>
+  <div
+    class="choice-group__options"
+    style={`--choice-group-columns: ${options.length}`}
+  >
+    {
+      options.map((option) => {
+        const Icon = option.icon;
+
+        return (
+          <label class="choice-group__option" data-tone={option.tone}>
+            <input
+              class="choice-group__input"
+              type="radio"
+              name={name}
+              value={option.value}
+              checked={option.value === value}
+              required={required}
+            />
+            {Icon ? <Icon class="choice-group__icon" /> : null}
+            <span class="choice-group__label">{option.label}</span>
+          </label>
+        );
+      })
+    }
+  </div>
+</fieldset>

package/src/components/forms/ChoiceGroup/ChoiceGroup.css

@@ -0,0 +1,108 @@
+.choice-group {
+  min-inline-size: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+
+.choice-group__legend {
+  margin-block-end: var(--nox-space-2);
+  padding: 0;
+  color: var(--nox-text-muted);
+  font-size: var(--nox-font-size-xs);
+  font-weight: var(--nox-font-weight-strong);
+  letter-spacing: var(--nox-letter-spacing-wide);
+  line-height: var(--nox-line-height-tight);
+  text-transform: uppercase;
+}
+
+.choice-group__options {
+  display: grid;
+  min-inline-size: 0;
+  grid-template-columns: repeat(
+    var(--choice-group-columns),
+    minmax(0, 1fr)
+  );
+  gap: var(--nox-space-2);
+}
+
+.choice-group__option {
+  position: relative;
+  display: flex;
+  min-inline-size: 0;
+  block-size: var(--nox-field-control-block-size);
+  align-items: center;
+  justify-content: center;
+  gap: var(--nox-space-2);
+  padding: var(--nox-space-2) var(--nox-space-3);
+  overflow: hidden;
+  border: var(--nox-border-width) solid var(--nox-field-border);
+  border-radius: var(--nox-radius-sm);
+  background: var(--nox-field-background);
+  color: var(--nox-text);
+  cursor: pointer;
+}
+
+.choice-group__input {
+  position: absolute;
+  inset: 0;
+  margin: 0;
+  opacity: 0;
+  cursor: pointer;
+}
+
+.choice-group__icon {
+  flex: 0 0 auto;
+  inline-size: 1rem;
+  block-size: 1rem;
+  color: var(--nox-tone-color);
+}
+
+.choice-group__label {
+  min-inline-size: 0;
+  overflow: hidden;
+  font-size: var(--nox-font-size-xs);
+  font-weight: var(--nox-font-weight-strong);
+  letter-spacing: var(--nox-letter-spacing-wide);
+  line-height: 1;
+  text-overflow: ellipsis;
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
+.choice-group__option:not(:has(.choice-group__input:checked)) {
+  background: var(--nox-field-background-disabled);
+  color: var(--nox-text-disabled);
+  opacity: 0.58;
+}
+
+.choice-group__option:has(.choice-group__input:checked) {
+  border-color: var(--nox-tone-color);
+  background: color-mix(
+    in srgb,
+    var(--nox-tone-seed) 12%,
+    var(--nox-mix-light)
+  );
+  color: var(--nox-tone-text);
+}
+
+.choice-group__option:has(.choice-group__input:focus-visible) {
+  border-color: var(--nox-tone-color);
+  box-shadow: var(--nox-field-focus-shadow);
+}
+
+.choice-group:disabled .choice-group__option {
+  background: var(--nox-field-background-disabled);
+  color: var(--nox-text-disabled);
+  cursor: not-allowed;
+}
+
+.choice-group:disabled .choice-group__input {
+  cursor: not-allowed;
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .choice-group:not(:disabled) .choice-group__option:hover {
+    border-color: var(--nox-tone-color);
+  }
+}

package/src/components/forms/ChoiceGroup/contracts.ts

@@ -0,0 +1,9 @@
+import type { AstroComponent } from '../../widgetTypes';
+import type { Tone } from '../../../theme/contracts';
+
+export type ChoiceOption = {
+  icon?: AstroComponent;
+  label: string;
+  tone?: Tone;
+  value: string;
+};

package/src/components/forms/DateTimeInput/DateTimeInput.astro

@@ -0,0 +1,14 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import type { Tone } from '../../../theme/contracts';
+import TextInput from '../TextInput/TextInput.astro';
+
+type Props = Omit<HTMLAttributes<'input'>, 'type'> & {
+  invalid?: boolean;
+  tone?: Tone;
+};
+
+const props: Props = Astro.props;
+---
+
+<TextInput {...props} type="datetime-local" clearable={false} />

package/src/components/forms/TextInput/TextInput.astro

@@ -1,10 +1,11 @@
 ---
 import type { HTMLAttributes } from 'astro/types';
+import type { PreferenceBinding } from '../../../client/preferences';
 import type { Tone } from '../../../theme/contracts';
 import CloseIcon from '../../icons/CloseIcon.astro';
 
 type TextInputFraming = 'embedded' | 'standalone';
-type TextInputType = 'search' | 'text';
+type TextInputType = 'datetime-local' | 'search' | 'text';
 type TextInputAutofocus = boolean | 'desktop';
 
 type Props = Omit<HTMLAttributes<'input'>, 'autofocus' | 'type'> & {
@@ -13,6 +14,7 @@ type Props = Omit<HTMLAttributes<'input'>, 'autofocus' | 'type'> & {
   clearLabel?: string;
   framing?: TextInputFraming;
   invalid?: boolean;
+  preference?: PreferenceBinding;
   tone?: Tone;
   type?: TextInputType;
 };
@@ -26,6 +28,7 @@ const {
   'data-tone': dataTone,
   framing = 'standalone',
   invalid = false,
+  preference,
   tone,
   type = 'text',
   ...attrs
@@ -43,6 +46,9 @@ const resolvedTone = tone ?? dataTone;
   data-tone={resolvedTone}
   data-text-input-autofocus={autofocus === 'desktop' ? 'desktop' : undefined}
   data-text-input-field
+  data-preference-id={preference?.id}
+  data-preference-path={preference?.path}
+  data-preference-control={preference ? 'text' : undefined}
 >
   <input
     {...attrs}

package/src/components/forms/Textarea/Textarea.astro

@@ -0,0 +1,32 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import type { Tone } from '../../../theme/contracts';
+
+type Props = HTMLAttributes<'textarea'> & {
+  invalid?: boolean;
+  tone?: Tone;
+  value?: string;
+};
+
+const {
+  'aria-invalid': ariaInvalid,
+  class: className,
+  'data-tone': dataTone,
+  invalid = false,
+  tone,
+  value = '',
+  ...attrs
+}: Props = Astro.props;
+const resolvedInvalid =
+  invalid || ariaInvalid === true || ariaInvalid === 'true';
+const resolvedTone = tone ?? dataTone;
+---
+
+<textarea
+  {...attrs}
+  class:list={['textarea', className]}
+  data-widget="textarea"
+  data-invalid={resolvedInvalid ? true : undefined}
+  data-tone={resolvedTone}
+  aria-invalid={resolvedInvalid ? 'true' : ariaInvalid}
+>{value}</textarea>