claude-artifact-framework 0.16.0 → 0.17.0

package/README.md

@@ -422,6 +422,30 @@ The active tab and each accordion's open/closed state are framework-owned
 view state — they survive reload, per viewer. Tabs cannot nest inside tabs;
 `when` must be a function; both throw otherwise.
 
+**When tabs ARE the app** — one tabs block as the whole UI, 4-5 sections
+the user hops between on a phone — declare bottom navigation:
+
+```js
+ArtifactKit.createApp({
+  title: "Mi Gym",
+  mobile: { nav: "bottom" },
+  blocks: [
+    { tabs: [
+      { label: "Hoy", icon: "💪", blocks: [...] },
+      { label: "Progreso", icon: "📈", blocks: [...] },
+      // ...up to ~5 sections
+    ], wide: true },
+  ],
+})
+```
+
+On a phone the first top-level tabs block's bar pins to the bottom of the
+screen (icons above labels, every section visible and thumb-reachable);
+on desktop nothing changes. Measured reason to bother: a top tab bar with
+5 sections overflows sideways at phone width and silently hides the last
+sections behind a scroll nobody sees. Declaring `mobile: { nav: "bottom" }`
+without a top-level tabs block throws.
+
 ### The `machine` — declared phases instead of hand-rolled state logic
 
 If your app has **phases** — a game (choosing → comparing → won), a turn
@@ -832,7 +856,8 @@ Everything an app can declare, in one place.
 
 **Top-level keys**: `title`, `subtitle`, `theme: { seed }`, `layout`, `blocks`,
 `records`, `steps`, `chat`, `main`, `sidebar` (workspace panes), `documents`,
-`data`, `shared`, `libs`. Anything else throws.
+`data`, `shared`, `libs`, `machine`, `brand`, `mobile: { nav: "bottom" }`.
+Anything else throws.
 
 **Layouts** (`layout:`): `panel` (default — grid of blocks), `records` (CRUD
 list), `steps` (wizard), `chat` (conversation with Claude), `workspace`

package/dist/index.esm.js

@@ -1438,7 +1438,8 @@ var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "colla
 var BRAND_KEYS = ["logo", "footer"];
 var BANNER_KEYS = ["image", "title", "subtitle"];
 var IMAGE_KEYS = ["src", "caption", "fit", "height"];
-var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents", "machine", "brand"];
+var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents", "machine", "brand", "mobile"];
+var MOBILE_KEYS = ["nav"];
 var MACHINE_KEYS = ["key", "initial", "states", "events"];
 var MACHINE_STATE_KEYS = ["after"];
 var MACHINE_AFTER_KEYS = ["seconds", "then", "do"];
@@ -1641,6 +1642,14 @@ function checkMachine(m) {
     }
   }
 }
+function findNavTabs(spec) {
+  for (const list of [spec.blocks, spec.main]) {
+    if (!Array.isArray(list)) continue;
+    const found = list.find((b) => b && Array.isArray(b.tabs));
+    if (found) return found;
+  }
+  return null;
+}
 function validate(spec) {
   const unknownTop = Object.keys(spec).filter((k) => !TOP_KEYS.includes(k));
   if (unknownTop.length) {
@@ -1665,6 +1674,22 @@ function validate(spec) {
       throw new Error("claude-artifact-framework: `libs` must be an array of https:// script URLs.");
     }
   }
+  if (spec.mobile !== void 0) {
+    const unknownM = Object.keys(spec.mobile || {}).filter((k) => !MOBILE_KEYS.includes(k));
+    if (unknownM.length) {
+      throw new Error(
+        `claude-artifact-framework: mobile has unknown keys (${unknownM.join(", ")}). Valid keys: ${MOBILE_KEYS.join(", ")}.`
+      );
+    }
+    if (spec.mobile.nav !== void 0 && spec.mobile.nav !== "bottom") {
+      throw new Error('claude-artifact-framework: mobile.nav only accepts "bottom" (omit `mobile` for the default top tab bar).');
+    }
+    if (spec.mobile.nav === "bottom" && !findNavTabs(spec)) {
+      throw new Error(
+        'claude-artifact-framework: mobile.nav: "bottom" moves a top-level `tabs` block\'s bar to the bottom of the phone screen \u2014 this spec has no top-level tabs block (in `blocks` or `main`) to move.'
+      );
+    }
+  }
   const layout = spec.layout || "panel";
   if (!LAYOUTS.includes(layout)) {
     throw new Error(
@@ -1946,17 +1971,18 @@ function boundary(React2) {
   }
   return BlockBoundary;
 }
-function TabsBlock({ spec, ctx }) {
+function TabsBlock({ spec, ctx, bottomNav }) {
   const tabs = spec.tabs;
   const key = tabs.map((t) => t.label).join("|");
   const stored = ctx.view.tabs ? ctx.view.tabs[key] : void 0;
   const active = Math.min(stored === void 0 ? 0 : stored, tabs.length - 1);
+  const bottom = !!bottomNav && ctx.viewport === "mobile";
   return createElement(
     "div",
     { className: "caf-tabs" },
     createElement(
       "div",
-      { className: "caf-tabbar", role: "tablist" },
+      { className: bottom ? "caf-tabbar caf-tabbar-bottom" : "caf-tabbar", role: "tablist" },
       tabs.map(
         (t, i) => createElement(
           "button",
@@ -1968,7 +1994,7 @@ function TabsBlock({ spec, ctx }) {
             className: i === active ? "caf-tab caf-tab-active" : "caf-tab",
             onClick: () => ctx.setTab(key, i)
           },
-          t.icon ? `${t.icon} ${t.label}` : t.label
+          bottom && t.icon ? [createElement("span", { key: "i", className: "caf-tab-ico", "aria-hidden": true }, t.icon), createElement("span", { key: "l", className: "caf-tab-lbl" }, t.label)] : t.icon ? `${t.icon} ${t.label}` : t.label
         )
       )
     ),
@@ -1984,13 +2010,14 @@ var ALL_NAMES = [...BLOCK_NAMES, "tabs", "records"];
 function Block({ block, ctx }) {
   if (typeof block.when === "function" && !block.when(ctx.data)) return null;
   if (block.state !== void 0 && ctx.machine && ctx.data[ctx.machine.key || "fase"] !== block.state) return null;
+  const bottomNav = ctx._navTabs !== void 0 && ctx._navTabs === block;
   if (block.icon && typeof block.title === "string") block = { ...block, title: `${block.icon} ${block.title}` };
   const name = Object.keys(block).find((k) => ALL_NAMES.includes(k));
   const Component2 = ALL_BLOCKS[name];
   const inner = createElement(
     boundary(ctx.React),
     null,
-    createElement(Component2, { spec: block.collapsible ? { ...block, title: void 0 } : block, ctx })
+    createElement(Component2, { spec: block.collapsible ? { ...block, title: void 0 } : block, ctx, bottomNav })
   );
   if (!block.collapsible) return inner;
   const key = typeof block.title === "string" && block.title ? block.title : name;
@@ -2376,6 +2403,7 @@ function createApp(spec = {}) {
       toggleCollapsed: (key, val) => state.setView({ collapsed: { ...state.getView().collapsed, [key]: val } }),
       colors: (n) => seriesColors(spec.theme && spec.theme.seed, n),
       viewport: narrow ? "mobile" : "desktop",
+      _navTabs: narrow && spec.mobile && spec.mobile.nav === "bottom" ? findNavTabs(spec) : null,
       machine: spec.machine || null,
       send: spec.machine ? (eventName, payload) => runMachineEvent(spec.machine, state.update, eventName, payload) : () => {
         throw new Error("claude-artifact-framework: ctx.send() needs a `machine` declared at the top level.");
@@ -2392,7 +2420,7 @@ function createApp(spec = {}) {
       "div",
       // The layout class lets shared CSS follow the active container width —
       // e.g. the header must share the workspace's wider axis, not panel's.
-      { className: `caf-root caf-layout-${layout}` },
+      { className: `caf-root caf-layout-${layout}${ctx._navTabs ? " caf-has-bottomnav" : ""}` },
       createElement("style", { dangerouslySetInnerHTML: { __html: css } }),
       createElement(
         "header",
@@ -2662,6 +2690,27 @@ var BASE_CSS = `
 /* Never-clip guarantee: content inside a custom block that is wider than the
    phone (column grids, week views) must scroll, not disappear off-screen. */
 .caf-custom { overflow-x: auto; }
+/* mobile.nav: "bottom" \u2014 the app-shell tab bar pinned to the thumb zone.
+   Tabs share the width evenly so every section stays visible; the root
+   reserves space so the bar never covers the end of the content. */
+.caf-has-bottomnav { padding-bottom: 76px; }
+.caf-tabbar-bottom {
+  position: fixed; bottom: 0; left: 0; right: 0; z-index: 40;
+  gap: 0; margin: 0; overflow-x: visible;
+  background: var(--caf-surface); border-top: 1px solid var(--caf-border); border-bottom: none;
+  padding: 0.25rem 0.4rem calc(0.3rem + env(safe-area-inset-bottom, 0px));
+  box-shadow: 0 -1px 6px rgba(0, 0, 0, 0.07);
+}
+.caf-tabbar-bottom .caf-tab {
+  flex: 1 1 0; min-width: 0; min-height: 48px;
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: 0.15rem; padding: 0.25rem 0.2rem; margin-bottom: 0;
+  font-size: 0.66rem; border-bottom: none;
+  overflow: hidden; text-overflow: ellipsis;
+}
+.caf-tabbar-bottom .caf-tab-ico { font-size: 1.25rem; line-height: 1; }
+.caf-tabbar-bottom .caf-tab-lbl { max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.caf-tabbar-bottom .caf-tab-active, .caf-tabbar-bottom .caf-tab-active:hover { border-bottom-color: transparent; }
 /* Touch devices get tappable framework controls regardless of the spec. */
 @media (pointer: coarse) {
   .caf-btn, .caf-tab, .caf-field input, .caf-field select { min-height: 44px; }