claude-artifact-framework 0.14.1 → 0.15.0

package/README.md

@@ -631,6 +631,44 @@ ArtifactKit.createApp({
 })
 ```
 
+### Brand — logo, banner, images, icons, avatars
+
+Identity without uploads. Artifacts can't persist real image files (the
+~5MB pool), so every brand element is **zero-asset-first**: it works with
+nothing, and a real asset is an optional upgrade.
+
+```js
+ArtifactKit.createApp({
+  title: "Napoli Pizzas",
+  subtitle: "Del horno a tu mesa",
+  theme: { seed: "#c2410c" },
+  brand: {
+    // the logo ladder: omit → automatic monogram (initials over the accent);
+    // an emoji; an inline <svg>...</svg> (best: you can WRITE one); or an https URL
+    logo: '<svg viewBox="0 0 24 24">...</svg>',
+    footer: "Napoli Pizzas — pedidos al 11-5555-5555",
+  },
+  blocks: [
+    // full-width hero; with no image it paints a gradient derived from the seed
+    { banner: { title: "Promo de julio", subtitle: "2x1 los martes", image: "https://..." } },
+    { image: { src: "https://... o un <svg> inline", caption: "El local", fit: "cover" } },
+    { text: "...", title: "Horarios", icon: "🕐" },   // icon prefixes any block title
+  ],
+})
+```
+
+- **`brand.logo`** renders beside the title; **`brand.footer`** closes the
+  page. Banner keys: `image`, `title`, `subtitle`. Image keys: `src`,
+  `caption`, `fit` (`cover`/`contain`), `height`.
+- **`icon` (an emoji) goes on any block, any tab, and any document type** —
+  emoji are zero bytes, work in both themes, and read as a consistent icon
+  set. Don't mix emoji icons with image icons in one app.
+- **`avatar: true` on records** draws an initials circle per row, colored
+  deterministically from the row title through the theme palette — a CRM or
+  ranking looks finished with no images at all.
+- Prefer inline SVG over URLs for logos and small graphics: no network, no
+  broken-image state, theme-controllable. Reserve URLs for real photos.
+
 ### External libraries, uploaded files, full-bleed custom, viewer identity
 
 Four primitives for the custom-heavy end of the spectrum (document viewers,
@@ -922,3 +960,6 @@ The rules that decide whether a generated app works, all in one place
     `marked(...)`); pin versions; when unsure of the file path use the bare
     package URL.
 12. **Framework ids are strings** — never `Number(record.id)`.
+13. **Brand is zero-asset-first** — monogram/gradient/emoji defaults before
+    URLs; inline `<svg>` over remote images; one icon style per app
+    (emoji-first); `avatar: true` instead of hand-built initials circles.

package/dist/index.esm.js

@@ -780,6 +780,32 @@ function OutputBlock({ spec, ctx }) {
     )
   );
 }
+function BannerBlock({ spec, ctx }) {
+  const b = typeof spec.banner === "string" ? { title: spec.banner } : spec.banner || {};
+  const [c1, c2] = ctx.colors(2);
+  const background = b.image ? `linear-gradient(rgba(0,0,0,0.35), rgba(0,0,0,0.35)), url(${JSON.stringify(b.image)}) center / cover` : `linear-gradient(135deg, ${c1}, ${c2})`;
+  return createElement(
+    "div",
+    { className: "caf-banner", style: { background } },
+    b.title ? createElement("h2", { className: "caf-banner-title" }, b.title) : null,
+    b.subtitle ? createElement("p", { className: "caf-banner-sub" }, b.subtitle) : null
+  );
+}
+function ImageBlock({ spec }) {
+  const im = typeof spec.image === "string" ? { src: spec.image } : spec.image || {};
+  const isSvg = typeof im.src === "string" && im.src.trim().startsWith("<svg");
+  return createElement(
+    "figure",
+    { className: "caf-block caf-image" },
+    spec.title ? createElement("h2", { className: "caf-block-title" }, spec.title) : null,
+    isSvg ? createElement("div", { className: "caf-image-svg", dangerouslySetInnerHTML: { __html: im.src } }) : createElement("img", {
+      src: im.src,
+      alt: im.caption || spec.title || "",
+      style: { objectFit: im.fit || "cover", maxHeight: im.height ? `${im.height}px` : void 0 }
+    }),
+    im.caption ? createElement("figcaption", { className: "caf-hint" }, im.caption) : null
+  );
+}
 function TextBlock({ spec, ctx }) {
   const body = typeof spec.text === "function" ? spec.text(ctx.data) : spec.text;
   return createElement(
@@ -1011,6 +1037,8 @@ var BLOCKS = {
   chart: ChartBlock,
   timer: TimerBlock,
   actions: ActionsBlock,
+  banner: BannerBlock,
+  image: ImageBlock,
   chat: ({ spec, ctx }) => createElement(ChatPanel, { cfg: spec.chat, ctx, title: spec.title }),
   custom: CustomBlock
 };
@@ -1042,6 +1070,13 @@ function recordDefaults(fields) {
 function makeId() {
   return "r" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
 }
+function Avatar({ title, ctx }) {
+  const initials = String(title).split(/\s+/).map((w) => w[0]).filter(Boolean).slice(0, 2).join("").toUpperCase() || "?";
+  let hash = 0;
+  for (const ch of String(title)) hash = hash * 31 + ch.charCodeAt(0) >>> 0;
+  const palette2 = ctx.colors(8);
+  return createElement("span", { className: "caf-avatar", style: { background: palette2[hash % palette2.length] } }, initials);
+}
 function rowTitle(spec, rec) {
   if (spec.title) return spec.title(rec);
   const f = spec.fields.find((f2) => !f2.type || f2.type === "text" || f2.type === "textarea" || f2.type === "select");
@@ -1125,11 +1160,16 @@ function ListScreen({ spec, ctx }) {
           "button",
           {
             type: "button",
-            className: "caf-row",
+            className: spec.avatar ? "caf-row caf-row-avatar" : "caf-row",
             onClick: () => ctx.go("record", rec.id)
           },
-          createElement("span", { className: "caf-row-title" }, rowTitle(spec, rec)),
-          spec.subtitle ? createElement("span", { className: "caf-row-sub" }, spec.subtitle(rec)) : null
+          spec.avatar ? createElement(Avatar, { title: rowTitle(spec, rec), ctx }) : null,
+          createElement(
+            "span",
+            { className: "caf-row-main" },
+            createElement("span", { className: "caf-row-title" }, rowTitle(spec, rec)),
+            spec.subtitle ? createElement("span", { className: "caf-row-sub" }, spec.subtitle(rec)) : null
+          )
         ),
         spec.actions ? createElement(
           "div",
@@ -1394,14 +1434,17 @@ function StepsLayout({ spec, ctx }) {
 
 // src/app.js
 var LAYOUTS = ["panel", "records", "steps", "chat", "workspace", "documents"];
-var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill", "state"];
-var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents", "machine"];
+var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill", "state", "icon"];
+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 MACHINE_KEYS = ["key", "initial", "states", "events"];
 var MACHINE_STATE_KEYS = ["after"];
 var MACHINE_AFTER_KEYS = ["seconds", "then", "do"];
 var MACHINE_EVENT_KEYS = ["from", "do", "then"];
 var DOCUMENTS_KEYS = ["label", "title", "blocks", "empty", "types"];
-var RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute", "items", "actions"];
+var RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute", "items", "actions", "avatar"];
 var ITEMS_KEYS = ["label", "fields", "empty"];
 function checkFields(fields, where) {
   for (const f of fields || []) {
@@ -1481,6 +1524,25 @@ function checkBlocks(blocks) {
     if (known[0] === "actions") checkActions(block.actions, `blocks[${i}].actions`);
     if (known[0] === "chat") checkChatConfig(block.chat, `blocks[${i}].chat`);
     if (known[0] === "records") checkRecordsSpec(block.records, `blocks[${i}].records`, true);
+    if (known[0] === "banner" && typeof block.banner === "object" && block.banner !== null) {
+      const unknownBn = Object.keys(block.banner).filter((k) => !BANNER_KEYS.includes(k));
+      if (unknownBn.length) {
+        throw new Error(
+          `claude-artifact-framework: blocks[${i}].banner has unknown keys (${unknownBn.join(", ")}). Valid keys: ${BANNER_KEYS.join(", ")}.`
+        );
+      }
+    }
+    if (known[0] === "image" && typeof block.image === "object" && block.image !== null) {
+      const unknownIm = Object.keys(block.image).filter((k) => !IMAGE_KEYS.includes(k));
+      if (unknownIm.length) {
+        throw new Error(
+          `claude-artifact-framework: blocks[${i}].image has unknown keys (${unknownIm.join(", ")}). Valid keys: ${IMAGE_KEYS.join(", ")}.`
+        );
+      }
+    }
+    if (block.icon !== void 0 && typeof block.icon !== "string") {
+      throw new Error(`claude-artifact-framework: blocks[${i}].icon must be a string (an emoji works best).`);
+    }
     if (known[0] === "tabs") {
       const tabs = block.tabs;
       if (!Array.isArray(tabs) || tabs.length === 0) {
@@ -1587,6 +1649,17 @@ function validate(spec) {
     );
   }
   if (spec.machine !== void 0) checkMachine(spec.machine);
+  if (spec.brand !== void 0) {
+    const unknownB = Object.keys(spec.brand || {}).filter((k) => !BRAND_KEYS.includes(k));
+    if (unknownB.length) {
+      throw new Error(
+        `claude-artifact-framework: brand has unknown keys (${unknownB.join(", ")}). Valid keys: ${BRAND_KEYS.join(", ")}.`
+      );
+    }
+    if (spec.brand.logo !== void 0 && typeof spec.brand.logo !== "string") {
+      throw new Error("claude-artifact-framework: brand.logo must be a string \u2014 an emoji, an inline <svg>...</svg>, or an https URL. Omit it for an automatic monogram.");
+    }
+  }
   if (spec.libs !== void 0) {
     if (!Array.isArray(spec.libs) || spec.libs.some((u) => typeof u !== "string" || !/^https?:\/\//.test(u))) {
       throw new Error("claude-artifact-framework: `libs` must be an array of https:// script URLs.");
@@ -1700,7 +1773,7 @@ function validate(spec) {
       }
       for (const name of names) {
         const t = d.types[name];
-        const TYPE_KEYS = ["label", "title", "blocks", "empty"];
+        const TYPE_KEYS = ["label", "title", "blocks", "empty", "icon"];
         const unknownT = Object.keys(t || {}).filter((k) => !TYPE_KEYS.includes(k));
         if (unknownT.length) {
           throw new Error(
@@ -1895,7 +1968,7 @@ function TabsBlock({ spec, ctx }) {
             className: i === active ? "caf-tab caf-tab-active" : "caf-tab",
             onClick: () => ctx.setTab(key, i)
           },
-          t.label
+          t.icon ? `${t.icon} ${t.label}` : t.label
         )
       )
     ),
@@ -1911,6 +1984,7 @@ 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;
+  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(
@@ -1945,9 +2019,9 @@ function Panel({ spec, ctx }) {
     (spec.blocks || []).map(
       (block, i) => createElement(
         "section",
-        // A collapsible is always full-width: half-width accordions leave an
-        // orphaned right edge on desktop and change width across breakpoints.
-        { key: i, className: block.wide || block.collapsible ? "caf-slot caf-slot-wide" : "caf-slot" },
+        // Collapsibles and banners are always full-width: half-width versions
+        // leave an orphaned right edge on desktop and change across breakpoints.
+        { key: i, className: block.wide || block.collapsible || block.banner ? "caf-slot caf-slot-wide" : "caf-slot" },
         createElement(Block, { block, ctx })
       )
     )
@@ -1965,9 +2039,9 @@ function RecordsWithBlocks({ spec, ctx }) {
       spec.blocks.map(
         (block, i) => createElement(
           "section",
-          // A collapsible is always full-width: half-width accordions leave an
-          // orphaned right edge on desktop and change width across breakpoints.
-          { key: i, className: block.wide || block.collapsible ? "caf-slot caf-slot-wide" : "caf-slot" },
+          // Collapsibles and banners are always full-width: half-width versions
+          // leave an orphaned right edge on desktop and change across breakpoints.
+          { key: i, className: block.wide || block.collapsible || block.banner ? "caf-slot caf-slot-wide" : "caf-slot" },
           createElement(Block, { block, ctx })
         )
       )
@@ -2028,7 +2102,10 @@ function DocumentsLayout({ spec, ctx }) {
   const types = dspec.types || null;
   const typeNames = types ? Object.keys(types) : [];
   const specFor = (doc) => types ? types[doc.type] : dspec;
-  const typeLabel = (name) => types[name] && types[name].label || name;
+  const typeLabel = (name) => {
+    const t = types[name] || {};
+    return (t.icon ? t.icon + " " : "") + (t.label || name);
+  };
   const [picking, setPicking] = useState(false);
   const storedId = ctx.view.tabs ? ctx.view.tabs[DOC_TAB_KEY] : void 0;
   const active = docs.find((doc) => doc.id === storedId) || docs[0];
@@ -2295,6 +2372,12 @@ function createApp(spec = {}) {
       }
     };
     const Layout = LAYOUT_COMPONENTS[layout];
+    const logo = spec.brand && spec.brand.logo;
+    const logoEl = !spec.brand ? null : logo && logo.trim().startsWith("<svg") ? createElement("span", { className: "caf-logo caf-logo-svg", dangerouslySetInnerHTML: { __html: logo } }) : logo && /^https?:\/\//.test(logo) ? createElement("img", { className: "caf-logo", src: logo, alt: "" }) : logo ? createElement("span", { className: "caf-logo caf-logo-emoji", "aria-hidden": true }, logo) : createElement(
+      "span",
+      { className: "caf-logo caf-logo-mono", "aria-hidden": true },
+      (spec.title || "?").split(/\s+/).map((w) => w[0]).filter(Boolean).slice(0, 2).join("").toUpperCase()
+    );
     return createElement(
       "div",
       // The layout class lets shared CSS follow the active container width —
@@ -2303,16 +2386,22 @@ function createApp(spec = {}) {
       createElement("style", { dangerouslySetInnerHTML: { __html: css } }),
       createElement(
         "header",
-        { className: "caf-header" },
-        spec.title ? createElement("h1", null, spec.title) : null,
-        spec.subtitle ? createElement("p", null, spec.subtitle) : null
+        { className: spec.brand ? "caf-header caf-header-brand" : "caf-header" },
+        logoEl,
+        createElement(
+          "div",
+          { className: "caf-header-text" },
+          spec.title ? createElement("h1", null, spec.title) : null,
+          spec.subtitle ? createElement("p", null, spec.subtitle) : null
+        )
       ),
       libsState === "error" ? createElement(
         "div",
         { className: "caf-block caf-block-error" },
         createElement("strong", null, "A library failed to load"),
         createElement("code", null, libsError)
-      ) : !state.isHydrated() || libsState === "loading" ? createElement("div", { className: "caf-block caf-loading" }, libsState === "loading" ? "Loading libraries\u2026" : "Loading\u2026") : createElement(Layout, { spec, ctx })
+      ) : !state.isHydrated() || libsState === "loading" ? createElement("div", { className: "caf-block caf-loading" }, libsState === "loading" ? "Loading libraries\u2026" : "Loading\u2026") : createElement(Layout, { spec, ctx }),
+      spec.brand && spec.brand.footer ? createElement("footer", { className: "caf-footer" }, spec.brand.footer) : null
     );
   };
 }
@@ -2525,6 +2614,35 @@ var BASE_CSS = `
 .caf-empty .caf-btn { margin-top: 0.6rem; }
 .caf-records-block { display: flex; flex-direction: column; gap: 1rem; min-width: 0; }
 .caf-doc-typemenu { display: flex; gap: 0.5rem; flex-wrap: wrap; }
+.caf-header-brand { display: flex; align-items: center; gap: 0.8rem; }
+.caf-header-text { min-width: 0; }
+.caf-logo { flex: none; width: 40px; height: 40px; border-radius: 9px; object-fit: contain; }
+.caf-logo-emoji { display: flex; align-items: center; justify-content: center; font-size: 1.7rem; background: var(--caf-surface); border: 1px solid var(--caf-border); }
+.caf-logo-mono {
+  display: flex; align-items: center; justify-content: center;
+  background: var(--caf-accent); color: var(--caf-accentText);
+  font-size: 0.95rem; font-weight: 700; letter-spacing: 0.02em;
+}
+.caf-logo-svg { display: flex; align-items: center; justify-content: center; overflow: hidden; }
+.caf-logo-svg svg { width: 100%; height: 100%; }
+.caf-banner {
+  border-radius: var(--caf-radius); padding: 1.6rem 1.4rem; min-height: 110px;
+  display: flex; flex-direction: column; justify-content: flex-end; gap: 0.2rem;
+}
+.caf-banner-title { margin: 0; color: #fff; font-size: 1.4rem; font-weight: 700; letter-spacing: -0.01em; text-shadow: 0 1px 3px rgba(0,0,0,0.35); }
+.caf-banner-sub { margin: 0; color: rgba(255,255,255,0.92); font-size: 0.9rem; text-shadow: 0 1px 2px rgba(0,0,0,0.35); }
+.caf-image { margin: 0; }
+.caf-image img { width: 100%; border-radius: 7px; display: block; }
+.caf-image-svg svg { width: 100%; height: auto; display: block; }
+.caf-footer { max-width: 760px; margin: 2rem auto 0; padding-top: 0.8rem; border-top: 1px solid var(--caf-border); color: var(--caf-muted); font-size: 0.78rem; text-align: center; }
+.caf-layout-workspace .caf-footer { max-width: 1200px; }
+.caf-avatar {
+  flex: none; width: 30px; height: 30px; border-radius: 50%;
+  display: flex; align-items: center; justify-content: center;
+  color: #fff; font-size: 0.7rem; font-weight: 700; letter-spacing: 0.02em;
+}
+.caf-row-avatar { flex-direction: row; align-items: center; gap: 0.6rem; }
+.caf-row-main { display: flex; flex-direction: column; gap: 0.15rem; min-width: 0; }
 .caf-chevron-closed { transform: rotate(-90deg); }
 .caf-block-fill { border: none; background: transparent; padding: 0; overflow: auto; min-height: 320px; }
 .caf-empty, .caf-loading { color: var(--caf-muted); font-size: 0.9rem; text-align: center; padding: 1.6rem 1rem; }