@astronox/core 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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/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/content/CardBody/CardBody.css

@@ -56,8 +56,7 @@
 }
 
 .card-body a {
-  color: var(--nox-link);
-  text-underline-offset: 0.2em;
+  color: var(--nox-content-link-color);
 }
 
 .card-body strong {
@@ -65,6 +64,11 @@
   font-weight: var(--nox-font-weight-strong);
 }
 
+.card-body a strong {
+  color: inherit;
+  font-weight: var(--nox-content-link-emphasis-font-weight);
+}
+
 @container (width < 32rem) {
   .card-body__content {
     --nox-content-padding: var(--nox-space-4);

package/src/components/content/CardFooter/CardFooter.astro

@@ -18,6 +18,7 @@ const {
 }: Props = Astro.props;
 const resolvedTone = tone ?? dataTone;
 const hasAction = Astro.slots.has('action');
+const hasLeadingAction = Astro.slots.has('leading-action');
 const hasMedia = Boolean(media);
 ---
 
@@ -28,10 +29,18 @@ const hasMedia = Boolean(media);
   data-surface
   data-surface-sizing="content"
   data-has-action={hasAction ? true : undefined}
+  data-has-leading-action={hasLeadingAction ? true : undefined}
   data-has-media={hasMedia ? true : undefined}
   data-tone={resolvedTone}
 >
   <div class="card-footer__layout">
+    {
+      hasLeadingAction ? (
+        <div class="card-footer__leading-action">
+          <slot name="leading-action" />
+        </div>
+      ) : null
+    }
     {
       media ? (
         <div class="card-footer__media" aria-hidden="true">

package/src/components/content/CardFooter/CardFooter.css

@@ -31,6 +31,10 @@
   grid-template-columns: minmax(0, 1fr) var(--card-footer-size);
 }
 
+.card-footer[data-has-leading-action] .card-footer__layout {
+  grid-template-columns: var(--card-footer-size) minmax(0, 1fr);
+}
+
 .card-footer[data-has-media][data-has-action] .card-footer__layout {
   grid-template-columns:
     var(--card-footer-size)
@@ -38,6 +42,31 @@
     var(--card-footer-size);
 }
 
+.card-footer[data-has-leading-action][data-has-action]
+  .card-footer__layout {
+  grid-template-columns:
+    var(--card-footer-size)
+    minmax(0, 1fr)
+    var(--card-footer-size);
+}
+
+.card-footer[data-has-leading-action][data-has-media]
+  .card-footer__layout {
+  grid-template-columns:
+    var(--card-footer-size)
+    var(--card-footer-size)
+    minmax(0, 1fr);
+}
+
+.card-footer[data-has-leading-action][data-has-media][data-has-action]
+  .card-footer__layout {
+  grid-template-columns:
+    var(--card-footer-size)
+    var(--card-footer-size)
+    minmax(0, 1fr)
+    var(--card-footer-size);
+}
+
 .card-footer__media {
   display: grid;
   min-width: 0;
@@ -64,29 +93,42 @@
   align-items: center;
   padding: var(--nox-space-3) var(--nox-space-5);
   font-size: var(--nox-font-size-sm);
-  font-weight: var(--nox-font-weight-medium);
+  font-weight: var(--nox-font-weight-regular);
   line-height: var(--nox-line-height-tight);
   overflow-wrap: anywhere;
 }
 
 .card-footer__content a {
-  color: var(--nox-link);
-  text-underline-offset: 0.2em;
+  color: var(--nox-content-link-color);
+  font-weight: var(--nox-content-link-emphasis-font-weight);
 }
 
 .card-footer__content strong {
   font-weight: var(--nox-font-weight-strong);
 }
 
+.card-footer__content a strong {
+  font-weight: var(--nox-content-link-emphasis-font-weight);
+}
+
+.card-footer__leading-action,
 .card-footer__action {
   display: grid;
   min-width: 0;
   min-height: var(--card-footer-size);
   place-items: stretch;
   overflow: hidden;
+}
+
+.card-footer__leading-action {
+  border-inline-end: var(--nox-border-width) solid var(--surface-border-color);
+}
+
+.card-footer__action {
   border-inline-start: var(--nox-border-width) solid var(--surface-border-color);
 }
 
+.card-footer__leading-action > .nox-button[data-button-borderless],
 .card-footer__action > .nox-button[data-button-borderless] {
   --nox-button-background: transparent;
 }

package/src/components/content/CardLink/CardLink.astro

@@ -20,6 +20,7 @@ const {
   compactContent,
   compactText,
   compactVisual = 'show',
+  density = 'default',
   disabled = false,
   direction,
   full = false,
@@ -32,11 +33,15 @@ const {
   mediaSize = 'default',
   meta,
   mode = 'link',
+  textLayout = 'inline',
+  textTreatment = 'default',
   tone,
   title,
   ...attrs
 }: Props = Astro.props;
-const accessibleLabel = `${label} : ${title}${meta !== undefined ? ` ${meta}` : ''}`;
+const accessibleLabel = [label, title, meta]
+  .filter((value) => value !== undefined && value !== '')
+  .join(' ');
 const isDisabled = disabled || (mode === 'link' && !href);
 const isInteractive = mode === 'link' && !isDisabled;
 const Root = isInteractive ? 'a' : 'span';
@@ -65,6 +70,7 @@ const resolvedTone = tone ?? dataTone;
   data-collapse={collapse}
   data-compact-content={resolvedCompactContent}
   data-compact-visual={compactVisual}
+  data-density={density}
   data-disabled={isDisabled ? 'true' : 'false'}
   data-direction={direction}
   data-full={full ? 'true' : 'false'}
@@ -74,6 +80,7 @@ const resolvedTone = tone ?? dataTone;
   data-media-position={hasVisual ? mediaPosition : undefined}
   data-media-size={hasVisual ? mediaSize : undefined}
   data-mode={mode}
+  data-text-treatment={textTreatment}
   data-tone={resolvedTone}
 >
   <span class="card-link__layout">
@@ -109,12 +116,14 @@ const resolvedTone = tone ?? dataTone;
         <span class="card-link__compact-text" aria-hidden="true">
           {compactText}
         </span>
-        <span class="card-link__label">{label}</span>
+        {label ? <span class="card-link__label">{label}</span> : null}
         <TextPair
           class="card-link__text"
-          layout="inline"
+          layout={textLayout}
           primary={title}
+          primaryWeight={isInteractive ? 'medium' : 'strong'}
           secondary={meta}
+          secondaryWeight={textTreatment === 'heading' ? 'regular' : 'medium'}
         />
       </span>
     </span>