@astronox/core 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [

package/src/admin/cache.ts

@@ -0,0 +1,217 @@
+import type { AdminPage } from './contracts';
+
+export type AdminResourceCacheSerializer<TItem, TStored> = {
+  parse(value: unknown): TItem | null;
+  serialize(item: TItem): TStored;
+};
+
+export type AdminResourceCacheConfig<TItem, TStored> = {
+  collectionKey: string;
+  editorKey: string;
+  getKey(item: TItem): string;
+  serializer: AdminResourceCacheSerializer<TItem, TStored>;
+  sort(items: readonly TItem[]): TItem[];
+  ttlMs?: number;
+};
+
+type StoredPage<TStored> = {
+  expiresAt: number;
+  items: TStored[];
+  nextCursor?: string;
+};
+
+type StoredEditor<TStored> = {
+  actorId: string;
+  expiresAt: number;
+  item: TStored;
+};
+
+const localCursorPrefix = 'cache:';
+
+export function createAdminResourceCache<TItem, TStored>({
+  collectionKey,
+  editorKey,
+  getKey,
+  serializer,
+  sort,
+  ttlMs = 10 * 60 * 1000,
+}: AdminResourceCacheConfig<TItem, TStored>) {
+  const collectionCacheKey = (actorId: string) =>
+    `${collectionKey}:${encodeURIComponent(actorId)}`;
+  const editorCacheKey = (id: string) =>
+    `${editorKey}:${encodeURIComponent(id)}`;
+
+  const readSnapshot = (actorId: string): AdminPage<TItem> | null => {
+    try {
+      const key = collectionCacheKey(actorId);
+      const raw = sessionStorage.getItem(key);
+      if (!raw) return null;
+      const stored = JSON.parse(raw) as Partial<StoredPage<TStored>>;
+      if (
+        typeof stored.expiresAt !== 'number' ||
+        stored.expiresAt <= Date.now() ||
+        !Array.isArray(stored.items)
+      ) {
+        sessionStorage.removeItem(key);
+        return null;
+      }
+
+      const items: TItem[] = [];
+      for (const value of stored.items) {
+        const item = serializer.parse(value);
+        if (!item) {
+          sessionStorage.removeItem(key);
+          return null;
+        }
+        items.push(item);
+      }
+
+      return {
+        items: sort(items),
+        nextCursor:
+          typeof stored.nextCursor === 'string' ? stored.nextCursor : undefined,
+      };
+    } catch {
+      return null;
+    }
+  };
+
+  const write = (actorId: string, page: AdminPage<TItem>): void => {
+    try {
+      const payload: StoredPage<TStored> = {
+        expiresAt: Date.now() + ttlMs,
+        items: sort(page.items).map(serializer.serialize),
+        nextCursor: page.nextCursor,
+      };
+      sessionStorage.setItem(
+        collectionCacheKey(actorId),
+        JSON.stringify(payload),
+      );
+    } catch {
+      // Storage is an optimization and must never block administration.
+    }
+  };
+
+  return {
+    editorKey,
+    isLocalCursor(cursor?: string): boolean {
+      return cursor?.startsWith(localCursorPrefix) === true;
+    },
+    read(
+      actorId: string,
+      input?: { cursor?: string; limit?: number },
+    ): AdminPage<TItem> | null {
+      const cached = readSnapshot(actorId);
+      if (!cached) return null;
+      if (input?.cursor && !input.cursor.startsWith(localCursorPrefix)) {
+        return null;
+      }
+      const offset = input?.cursor
+        ? Number.parseInt(input.cursor.slice(localCursorPrefix.length), 10)
+        : 0;
+      if (!Number.isSafeInteger(offset) || offset < 0) return null;
+      const limit = Math.max(1, Math.floor(input?.limit ?? 25));
+      const end = Math.min(cached.items.length, offset + limit);
+      return {
+        items: cached.items.slice(offset, end),
+        nextCursor:
+          end < cached.items.length
+            ? `${localCursorPrefix}${end}`
+            : cached.nextCursor,
+      };
+    },
+    find(actorId: string, id: string): TItem | null {
+      return (
+        readSnapshot(actorId)?.items.find((item) => getKey(item) === id) ??
+        null
+      );
+    },
+    readEditor(actorId: string, id: string): TItem | null {
+      try {
+        const key = editorCacheKey(id);
+        const raw = sessionStorage.getItem(key);
+        if (!raw) return null;
+        const stored = JSON.parse(raw) as Partial<StoredEditor<TStored>>;
+        if (
+          stored.actorId !== actorId ||
+          typeof stored.expiresAt !== 'number' ||
+          stored.expiresAt <= Date.now()
+        ) {
+          sessionStorage.removeItem(key);
+          return null;
+        }
+        return serializer.parse(stored.item);
+      } catch {
+        return null;
+      }
+    },
+    write,
+    append(actorId: string, page: AdminPage<TItem>): void {
+      const cached = readSnapshot(actorId);
+      if (!cached) return;
+      const items = new Map(cached.items.map((item) => [getKey(item), item]));
+      page.items.forEach((item) => items.set(getKey(item), item));
+      write(actorId, {
+        items: [...items.values()],
+        nextCursor: page.nextCursor,
+      });
+    },
+    upsert(actorId: string, item: TItem): void {
+      const cached = readSnapshot(actorId);
+      if (!cached) return;
+      const items = new Map(
+        cached.items.map((candidate) => [getKey(candidate), candidate]),
+      );
+      items.set(getKey(item), item);
+      write(actorId, {
+        items: [...items.values()],
+        nextCursor: cached.nextCursor,
+      });
+    },
+    remove(actorId: string, id: string): void {
+      const cached = readSnapshot(actorId);
+      if (cached) {
+        write(actorId, {
+          items: cached.items.filter((item) => getKey(item) !== id),
+          nextCursor: cached.nextCursor,
+        });
+      }
+      try {
+        sessionStorage.removeItem(editorCacheKey(id));
+      } catch {
+        // Cleanup is best effort.
+      }
+    },
+    writeEditor(actorId: string, item: TItem): boolean {
+      try {
+        const payload: StoredEditor<TStored> = {
+          actorId,
+          expiresAt: Date.now() + ttlMs,
+          item: serializer.serialize(item),
+        };
+        sessionStorage.setItem(
+          editorCacheKey(getKey(item)),
+          JSON.stringify(payload),
+        );
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    clear(actorId: string): void {
+      try {
+        sessionStorage.removeItem(collectionCacheKey(actorId));
+        for (let index = sessionStorage.length - 1; index >= 0; index -= 1) {
+          const key = sessionStorage.key(index);
+          if (!key?.startsWith(`${editorKey}:`)) continue;
+          const raw = sessionStorage.getItem(key);
+          if (!raw) continue;
+          const stored = JSON.parse(raw) as Partial<StoredEditor<TStored>>;
+          if (stored.actorId === actorId) sessionStorage.removeItem(key);
+        }
+      } catch {
+        // Cleanup is best effort.
+      }
+    },
+  } as const;
+}

package/src/admin/index.ts

@@ -1,2 +1,3 @@
 export * from './contracts';
+export * from './cache';
 export * from './module';

package/src/auth/firebase/client.ts

@@ -1,21 +1,47 @@
-import { getApps, initializeApp } from 'firebase/app';
+import { getApps, initializeApp, type FirebaseApp } from 'firebase/app';
 import {
+  browserLocalPersistence,
+  browserPopupRedirectResolver,
   GoogleAuthProvider,
   getAuth,
+  initializeAuth,
   onAuthStateChanged,
   signInWithPopup,
   signOut,
+  type Auth,
   type User,
 } from 'firebase/auth';
 import type { AuthActor } from '../contracts';
 import type { FirebaseClientConfig } from './contracts';
 
 export type FirebaseGoogleAuthClient = {
-  observe(listener: (actor: AuthActor | null) => void): () => void;
+  observe(
+    listener: (actor: AuthActor | null) => void,
+    onError?: (reason: unknown) => void,
+  ): () => void;
   signIn(): Promise<AuthActor>;
   signOut(): Promise<void>;
 };
 
+function initializeBrowserAuth(app: FirebaseApp): Auth {
+  try {
+    return initializeAuth(app, {
+      persistence: browserLocalPersistence,
+      popupRedirectResolver: browserPopupRedirectResolver,
+    });
+  } catch (reason) {
+    if (
+      typeof reason === 'object' &&
+      reason !== null &&
+      'code' in reason &&
+      reason.code === 'auth/already-initialized'
+    ) {
+      return getAuth(app);
+    }
+    throw reason;
+  }
+}
+
 function toAuthActor(user: User): AuthActor {
   return {
     id: user.uid,
@@ -32,15 +58,19 @@ export function createFirebaseGoogleAuthClient(
   const app =
     getApps().find((candidate) => candidate.name === config.projectId) ??
     initializeApp(config, config.projectId);
-  const auth = getAuth(app);
+  const auth = initializeBrowserAuth(app);
   const provider = new GoogleAuthProvider();
   provider.setCustomParameters({ prompt: 'select_account' });
 
   return {
-    observe(listener) {
-      return onAuthStateChanged(auth, (user) => {
-        listener(user ? toAuthActor(user) : null);
-      });
+    observe(listener, onError) {
+      return onAuthStateChanged(
+        auth,
+        (user) => {
+          listener(user ? toAuthActor(user) : null);
+        },
+        onError,
+      );
     },
     async signIn() {
       const result = await signInWithPopup(auth, provider);

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,5 +1,6 @@
 export * from './clipboard';
 export * from './focus';
+export * from './formSubmission';
 export * from './preferences';
 export * from './scroll';
 export * from '../components/content/MarkdownContent/markdownContentRenderer';

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

@@ -150,7 +150,7 @@
     background: color-mix(
       in srgb,
       var(--nox-button-hover-tone-seed) 12%,
-      var(--nox-mix-light)
+      var(--nox-theme-surface-base)
     );
     color: var(--nox-button-hover-tone-seed);
   }

package/src/components/actions/CardAction/CardAction.css

@@ -130,7 +130,7 @@
   background: color-mix(
     in srgb,
     var(--card-action-hover-seed) 12%,
-    var(--nox-mix-light)
+    var(--nox-theme-surface-base)
   );
 }
 
@@ -145,7 +145,7 @@
     background: color-mix(
       in srgb,
       var(--card-action-hover-seed) 12%,
-      var(--nox-mix-light)
+      var(--nox-theme-surface-base)
     );
   }
 }
@@ -154,7 +154,7 @@
   background: color-mix(
     in srgb,
     var(--card-action-hover-seed) 18%,
-    var(--nox-mix-light)
+    var(--nox-theme-surface-base)
   );
 }
 

package/src/components/actions/ScrollToTop/ScrollToTop.css

@@ -11,9 +11,20 @@
   block-size: var(--nox-section-compact-block-size);
   min-block-size: 0;
   box-shadow: var(--nox-shadow-surface);
+  opacity: 0.8;
+}
+
+.scroll-to-top.nox-button:is(:focus-visible, :active) {
+  opacity: 1;
 }
 
 html:has(dialog[open]) .scroll-to-top,
 html:has(:fullscreen) .scroll-to-top {
   display: none;
 }
+
+@media (hover: hover) and (pointer: fine) {
+  .scroll-to-top.nox-button:hover {
+    opacity: 1;
+  }
+}

package/src/components/actions/ThemeToggle/ThemeToggle.astro

@@ -0,0 +1,59 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import DayIcon from '../../icons/DayIcon.astro';
+import NightIcon from '../../icons/NightIcon.astro';
+
+type Props = HTMLAttributes<'button'> & {
+  appearance?: 'circle' | 'utility';
+  darkLabel: string;
+  lightLabel: string;
+};
+
+const {
+  appearance = 'circle',
+  class: className,
+  darkLabel,
+  lightLabel,
+  type = 'button',
+  ...attrs
+}: Props = Astro.props;
+---
+
+<button
+  {...attrs}
+  class:list={['theme-toggle', className]}
+  type={type}
+  aria-label={darkLabel}
+  title={darkLabel}
+  data-theme-toggle
+  data-theme-toggle-appearance={appearance}
+  data-theme-toggle-dark-label={darkLabel}
+  data-theme-toggle-light-label={lightLabel}
+  data-navigation-control={appearance === 'circle' ? '' : undefined}
+  data-navigation-control-appearance={
+    appearance === 'circle' ? 'bar' : undefined
+  }
+>
+  <span
+    class="theme-toggle__icon"
+    data-theme-toggle-target="dark"
+    aria-hidden="true"
+  >
+    <NightIcon />
+  </span>
+  <span
+    class="theme-toggle__icon"
+    data-theme-toggle-target="light"
+    aria-hidden="true"
+  >
+    <DayIcon />
+  </span>
+</button>
+
+<script>
+  import { initThemeToggle } from './themeToggleController';
+
+  for (const toggle of document.querySelectorAll('[data-theme-toggle]')) {
+    if (toggle instanceof HTMLElement) initThemeToggle(toggle);
+  }
+</script>

package/src/components/actions/ThemeToggle/ThemeToggle.css

@@ -0,0 +1,83 @@
+.theme-toggle {
+  display: grid;
+  flex: 0 0 auto;
+  place-items: center;
+  padding: 0;
+  border: var(--nox-border-width) solid var(--nox-border);
+  background: var(--nox-surface);
+  color: var(--nox-text-muted);
+  cursor: pointer;
+}
+
+.theme-toggle[data-theme-toggle-appearance='circle'] {
+  min-inline-size: 4.75rem;
+  block-size: 100%;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+}
+
+.theme-toggle[data-theme-toggle-appearance='utility'] {
+  inline-size: 100%;
+  min-block-size: var(--nox-navigation-block-size);
+  border-radius: var(--nox-radius-md);
+  background: var(--nox-surface-muted);
+}
+
+.theme-toggle__icon {
+  display: grid;
+  inline-size: 2rem;
+  block-size: 2rem;
+  grid-area: 1 / 1;
+  place-items: center;
+}
+
+.theme-toggle[data-theme-toggle-appearance='utility'] .theme-toggle__icon {
+  inline-size: 2.125rem;
+  block-size: 2.125rem;
+}
+
+.theme-toggle[data-theme-toggle-appearance='circle'] .theme-toggle__icon {
+  border: var(--nox-border-width) solid var(--nox-border);
+  border-radius: 50%;
+  background: var(--nox-surface);
+}
+
+.theme-toggle__icon > svg {
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+}
+
+.theme-toggle [data-theme-toggle-target='light'] {
+  display: none;
+}
+
+:root[data-theme='dark'] .theme-toggle [data-theme-toggle-target='dark'] {
+  display: none;
+}
+
+:root[data-theme='dark'] .theme-toggle [data-theme-toggle-target='light'] {
+  display: grid;
+}
+
+.theme-toggle:focus-visible {
+  outline: var(--nox-focus-ring-width) solid var(--nox-focus-ring);
+  outline-offset: var(--nox-focus-ring-offset);
+}
+
+@media (hover: hover) {
+  .theme-toggle:hover {
+    background: var(--nox-surface-strong);
+    color: var(--nox-link-hover);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .theme-toggle {
+    transition:
+      background-color var(--nox-motion-duration-sm)
+        var(--nox-motion-easing-standard),
+      color var(--nox-motion-duration-sm) var(--nox-motion-easing-standard);
+  }
+}