@at-flux/astroflare 1.0.0 → 1.0.1

package/README.md

@@ -33,8 +33,9 @@ import { forms } from '@at-flux/astroflare/core';
 
 ### Components (Astro)
 
-- `Modal.astro` — Headless modal using native `<dialog>` and `<app-modal>` web component
+- `Modal.astro` — Headless modal using native `<dialog>` and `<app-modal>` web component (`class` applies to the panel)
 - `ModalTrigger.astro` — Trigger that opens a modal by ID using `<modal-trigger>` web component
+- `Section.astro` — Page section with optional `narrow` and `contentOnly` (inner width wrapper without outer padding)
 - `ThemeToggle.astro` — Dark/light mode toggle using `<theme-toggle>` web component
 - `ClientRouterLoadingSpinner.astro` — Loading spinner for Astro view transitions
 
@@ -47,7 +48,28 @@ import { forms } from '@at-flux/astroflare/core';
 
 ## Usage
 
-### Local Import (file: protocol)
+### Local checkout without changing package.json or lockfile
+
+Keep **`@at-flux/astroflare`** on a normal semver range in `package.json` and run **`pnpm install`** so the lockfile records the registry version. Then overlay the install with a symlink (only under `node_modules`):
+
+```bash
+pnpm exec astroflare-link-local link /absolute/or/relative/path/to/astroflare/packages/astroflare
+# or
+ASTROFLARE_LOCAL_PATH=../../ts-libs/astroflare/packages/astroflare pnpm exec astroflare-link-local
+```
+
+- **`USE_LOCAL_ASTROFLARE=1`** (or `true` / `yes`) is supported only together with **`ASTROFLARE_LOCAL_PATH`** or **`USE_LOCAL_ASTROFLARE_PATH`** (path to `packages/astroflare`).
+- **`unlink`** removes the overlay and runs **`pnpm install`** again so `node_modules` matches the lockfile:
+
+```bash
+pnpm exec astroflare-link-local unlink
+```
+
+- **`status`** shows whether an overlay is active.
+
+Re-running **`pnpm install`** may replace the symlink with the store copy; run **`link`** again if that happens.
+
+### Local Import (file: protocol) — alternative
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@at-flux/astroflare",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Reusable headless components, styles, and utilities for Astro + Tailwind v4 + Cloudflare projects",
   "author": "Taylor Siviter <taylor@siviter.xyz>",
@@ -49,10 +49,14 @@
     "./components/*": "./src/components/*",
     "./styles/*": "./src/styles/*"
   },
+  "bin": {
+    "astroflare-link-local": "./scripts/link-local.mjs"
+  },
   "files": [
     "dist",
     "src/components",
     "src/styles",
+    "scripts/link-local.mjs",
     "README.md"
   ],
   "devDependencies": {

package/scripts/link-local.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * Overlay @at-flux/astroflare in node_modules with a symlink to a local checkout.
+ * Does not change package.json or the lockfile — run `pnpm install` first so the
+ * registry version is recorded, then this replaces only the on-disk resolution.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { platform } from 'node:os';
+
+const MARKER = '.astroflare-local-overlay.json';
+
+function findProjectRoot(start = process.cwd()) {
+  let dir = resolve(start);
+  for (;;) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (deps['@at-flux/astroflare']) {
+          return dir;
+        }
+      } catch {
+        /* continue */
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      console.error('astroflare-link-local: could not find a package.json that depends on @at-flux/astroflare');
+      process.exit(1);
+    }
+    dir = parent;
+  }
+}
+
+function markerPath(projectRoot) {
+  return join(projectRoot, 'node_modules', MARKER);
+}
+
+function nmTarget(projectRoot) {
+  return join(projectRoot, 'node_modules', '@at-flux', 'astroflare');
+}
+
+function resolveLocalPath(projectRoot, raw) {
+  if (!raw || typeof raw !== 'string') {
+    console.error(
+      'astroflare-link-local: pass a path to packages/astroflare, or set ASTROFLARE_LOCAL_PATH or USE_LOCAL_ASTROFLARE_PATH',
+    );
+    process.exit(1);
+  }
+  const abs = isAbsolute(raw) ? raw : resolve(projectRoot, raw);
+  const pkgJson = join(abs, 'package.json');
+  if (!existsSync(pkgJson)) {
+    console.error(`astroflare-link-local: not a package directory (missing package.json): ${abs}`);
+    process.exit(1);
+  }
+  try {
+    const { name } = JSON.parse(readFileSync(pkgJson, 'utf8'));
+    if (name !== '@at-flux/astroflare') {
+      console.error(`astroflare-link-local: expected name @at-flux/astroflare, got ${name}`);
+      process.exit(1);
+    }
+  } catch (e) {
+    console.error('astroflare-link-local: could not read local package.json', e);
+    process.exit(1);
+  }
+  return abs;
+}
+
+function symlinkType() {
+  return platform() === 'win32' ? 'junction' : 'dir';
+}
+
+function cmdLink(projectRoot, localAbs) {
+  const target = nmTarget(projectRoot);
+  const fluxScope = dirname(target);
+
+  rmSync(target, { recursive: true, force: true });
+  mkdirSync(fluxScope, { recursive: true });
+  symlinkSync(localAbs, target, symlinkType());
+
+  mkdirSync(join(projectRoot, 'node_modules'), { recursive: true });
+  writeFileSync(
+    markerPath(projectRoot),
+    `${JSON.stringify({ localPath: localAbs, linkedAt: new Date().toISOString() }, null, 2)}\n`,
+  );
+
+  console.log(`astroflare-link-local: linked\n  ${target}\n  → ${localAbs}`);
+  console.log('astroflare-link-local: package.json and lockfile unchanged. Run `pnpm install` again only if you need to restore the registry copy (or use `unlink`).');
+}
+
+function cmdUnlink(projectRoot, runInstall) {
+  const target = nmTarget(projectRoot);
+  const marker = markerPath(projectRoot);
+
+  rmSync(target, { recursive: true, force: true });
+  rmSync(marker, { force: true });
+
+  if (runInstall) {
+    const r = spawnSync('pnpm', ['install'], { cwd: projectRoot, stdio: 'inherit', shell: true });
+    if (r.error) {
+      console.error('astroflare-link-local: pnpm install failed:', r.error.message);
+      process.exit(r.status ?? 1);
+    }
+    if (r.status !== 0) {
+      process.exit(r.status ?? 1);
+    }
+    console.log('astroflare-link-local: restored @at-flux/astroflare from the lockfile.');
+  } else {
+    console.log('astroflare-link-local: removed overlay. Run `pnpm install` to restore node_modules.');
+  }
+}
+
+function cmdStatus(projectRoot) {
+  const marker = markerPath(projectRoot);
+  const target = nmTarget(projectRoot);
+  if (!existsSync(marker)) {
+    console.log('astroflare-link-local: no local overlay (registry / store layout).');
+    return;
+  }
+  try {
+    const data = JSON.parse(readFileSync(marker, 'utf8'));
+    console.log('astroflare-link-local: overlay active');
+    console.log(`  marker: ${marker}`);
+    console.log(`  local:  ${data.localPath}`);
+    if (existsSync(target)) {
+      console.log(`  node_modules: ${target}`);
+    }
+  } catch {
+    console.log('astroflare-link-local: marker present but invalid');
+  }
+}
+
+function localPathFromEnv() {
+  return process.env.ASTROFLARE_LOCAL_PATH || process.env.USE_LOCAL_ASTROFLARE_PATH || null;
+}
+
+function useLocalAstroflareEnv() {
+  const v = process.env.USE_LOCAL_ASTROFLARE;
+  return v === '1' || v === 'true' || v === 'yes';
+}
+
+const argv = process.argv.slice(2);
+
+if (argv[0] === 'help' || argv[0] === '-h' || argv[0] === '--help') {
+  console.log(`Usage:
+  astroflare-link-local [link] <path-to-packages/astroflare>
+  astroflare-link-local              # uses ASTROFLARE_LOCAL_PATH or USE_LOCAL_ASTROFLARE_PATH (required)
+  USE_LOCAL_ASTROFLARE=1 must be paired with a path via ASTROFLARE_LOCAL_PATH or USE_LOCAL_ASTROFLARE_PATH
+
+  astroflare-link-local unlink       # remove symlink; run pnpm install
+  astroflare-link-local unlink --no-install
+  astroflare-link-local status
+
+Symlinks node_modules/@at-flux/astroflare → local checkout. Does not edit package.json or lockfile.`);
+  process.exit(0);
+}
+
+const projectRoot = findProjectRoot();
+
+if (argv[0] === 'unlink') {
+  const noInstall = argv.includes('--no-install');
+  cmdUnlink(projectRoot, !noInstall);
+  process.exit(0);
+}
+
+if (argv[0] === 'status') {
+  cmdStatus(projectRoot);
+  process.exit(0);
+}
+
+let rawPath;
+if (argv[0] === 'link') {
+  rawPath = argv[1] ?? localPathFromEnv();
+} else if (argv[0]) {
+  rawPath = argv[0];
+} else {
+  rawPath = localPathFromEnv();
+}
+
+if (useLocalAstroflareEnv() && !rawPath) {
+  console.error(
+    'astroflare-link-local: USE_LOCAL_ASTROFLARE is set; also set ASTROFLARE_LOCAL_PATH or USE_LOCAL_ASTROFLARE_PATH (or pass a path).',
+  );
+  process.exit(1);
+}
+
+if (!rawPath) {
+  console.error('astroflare-link-local: missing path. Pass <path>, or set ASTROFLARE_LOCAL_PATH / USE_LOCAL_ASTROFLARE_PATH.');
+  console.error('Run: astroflare-link-local --help');
+  process.exit(1);
+}
+
+const localAbs = resolveLocalPath(projectRoot, rawPath);
+cmdLink(projectRoot, localAbs);

package/src/components/Modal.astro

@@ -1,44 +1,59 @@
 ---
 /**
- * Headless modal component using native <dialog>.
- * Provides no visual styling beyond structure -- consumers apply their own theme.
+ * Headless modal using native `<dialog>`.
+ * `class` applies to the modal panel (card). Dialog element keeps backdrop/transparent shell.
  */
 interface Props {
   id: string;
+  /** Panel (card) classes — surface, border, radius, etc. */
   class?: string;
   backdropClass?: string;
+  /** Extra panel classes merged after `class`. */
   panelClass?: string;
+  closeButtonClass?: string;
+  /** Scrollable inner wrapper around the default slot. */
+  contentClass?: string;
 }
 
 const {
   id,
   class: className = '',
-  backdropClass = 'backdrop:bg-black/80',
+  backdropClass = 'backdrop:bg-black/80 bg-transparent p-0 w-full h-full max-w-none max-h-none',
   panelClass = '',
+  closeButtonClass = 'absolute top-3 right-6 z-50 flex h-10 w-10 items-center justify-center rounded-full opacity-80 transition-opacity hover:opacity-100',
+  contentClass = 'relative overflow-y-auto max-h-[calc(100dvh-2rem)]',
 } = Astro.props;
 ---
 
 <app-modal>
-  <dialog
-    id={id}
-    class:list={['bg-transparent p-0 w-full h-full max-w-none max-h-none', backdropClass, className]}
-  >
-    <div class='flex items-center justify-center min-h-full p-0 md:p-4'>
+  <dialog id={id} class:list={[backdropClass]}>
+    <div class='flex min-h-full items-center justify-center p-0 md:p-4'>
       <div
-        class:list={['relative overflow-hidden outline-none w-[100dvw] max-w-4xl max-h-[100dvh]', panelClass]}
+        class:list={[
+          'relative max-h-[100dvh] w-[100dvw] max-w-4xl overflow-hidden outline-none',
+          className,
+          panelClass,
+        ]}
         role='dialog'
       >
-        <button
-          id={`${id}-close`}
-          class='absolute top-3 right-6 w-10 h-10 rounded-full z-50 flex items-center justify-center'
-          aria-label='Close modal'
-        >
-          <svg width='20' height='20' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'>
-            <path d='M18 6L6 18' /><path d='M6 6L18 18' />
+        <button class:list={[closeButtonClass]} type='button' aria-label='Close modal'>
+          <svg
+            width='20'
+            height='20'
+            viewBox='0 0 24 24'
+            fill='none'
+            stroke='currentColor'
+            stroke-width='2'
+            stroke-linecap='round'
+            stroke-linejoin='round'
+            aria-hidden='true'
+          >
+            <path d='M18 6L6 18'></path>
+            <path d='M6 6L18 18'></path>
           </svg>
         </button>
 
-        <div class='relative overflow-y-auto max-h-[calc(100dvh-2rem)]'>
+        <div class:list={[contentClass]}>
           <slot />
         </div>
       </div>
@@ -52,7 +67,7 @@ const {
       const dialog = this.querySelector<HTMLDialogElement>('dialog');
       if (!dialog) return;
 
-      const closeBtn = this.querySelector<HTMLButtonElement>(`#${dialog.id}-close`);
+      const closeBtn = this.querySelector<HTMLButtonElement>('button[aria-label="Close modal"]');
       closeBtn?.addEventListener('click', () => dialog.close());
     }
   }

package/src/components/Section.astro

@@ -0,0 +1,27 @@
+---
+interface Props {
+  id?: string;
+  class?: string;
+  narrow?: boolean;
+  /** Inner max-width wrapper only — no section padding (e.g. modal body). */
+  contentOnly?: boolean;
+}
+
+const { id, class: className = '', narrow = false, contentOnly = false } = Astro.props;
+
+const innerClass = ['mx-auto w-full', narrow ? 'max-w-4xl' : 'max-w-6xl'];
+---
+
+{
+  contentOnly ? (
+    <div class:list={innerClass}>
+      <slot />
+    </div>
+  ) : (
+    <section id={id} class:list={['px-6 pt-10 pb-16 md:px-8 md:pt-16 md:pb-24', className]}>
+      <div class:list={innerClass}>
+        <slot />
+      </div>
+    </section>
+  )
+}