npm - create-kywi-app - Versions diffs - 0.6.4 → 0.6.6 - Mend

create-kywi-app 0.6.4 → 0.6.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/assets/agent-patterns.md +40 -4
package/assets/kywi-custom-modules-skill.md +11 -1
package/lib/templates.mjs +24 -1
package/package.json +1 -1

package/assets/agent-patterns.md CHANGED Viewed

@@ -272,7 +272,7 @@ authored elsewhere in the admin).
 | `name` | Purpose |
 |---|---|
 | `variantContainer` | Module-level arms revealed client-side per audience — read §8 first |
-| `personalizationBadge` | Mount point for the "you're seeing X" transparency control |
+| `personalizationBadge` | Optional inline status pill that opens the global transparency panel — not needed on ordinary pages (§8) |
 | `socialShare` | Share links for a URL/title across networks |
 | `map` | Embedded map at a lat/lng or address |
 | `cookieConsent` | Consent banner with message + privacy-policy link |
@@ -308,8 +308,12 @@ Full recipe, worked example and hazards: the **`kywi-custom-modules` skill**.
 **Design the props for the owner, not for yourself.** The props panel gives the
 owner real controls for `text`/`textarea`/`richText` (text inputs),
 `image`/`file` (media picker), `boolean` (checkbox) and `number`/`date`/`color`
-(native inputs); `select`, `slug`, `relationship` and `multiSelect` fall back to
-a plain text input, so name the allowed values in the label. A `json` prop is a
+(native inputs); `select` and `multiSelect` render a real dropdown or checkbox
+group when the prop declares `options` — `{ value, label }` pairs, or bare
+strings where the string serves as both — so declare options for every closed
+choice instead of trusting the owner to type the right value. `slug` and
+`relationship` have no options field and are still plain text inputs; that's
+the one place to name the allowed values in the label. A `json` prop is a
 raw JSON textarea — developer territory. A "three stats" module with `stats: {
 type: 'json' }` has taken the copy away from the owner; the same module with
 `stat1Value` / `stat1Label` … as `text` props hasn't.
@@ -406,12 +410,44 @@ Four traps, each of which fails silently:
    audience arm first, so a visitor who matches an audience never enters the
    split. Don't run an experiment and an audience variant on the same container.
 4. **The client runtime needs `/kywi.js`.** Self-ID, behavioral re-evaluation
-   and the transparency badge no-op silently unless the built
+   and the transparency panel no-op silently unless the built
    `@kywi-software/js` bundle is at `public/kywi.js`.
 Standing rule: **the default arm must be complete on its own.** It is what
 search engines, answer engines, and every opted-out visitor receive.
+### Transparency: automatic, not something you place
+Once the client runtime is loaded, every personalized (or opted-out-with-a-
+match) page grows a global transparency surface on its own — a small
+collapsed pill, bottom of the page, that expands into a panel showing which
+audience the page was personalized for, an audience switcher, reset-to-
+automatic, and opt-out/opt-in. This is automatic and site-wide; you do not add
+anything to a page to get it.
+**Don't place the `personalizationBadge` module on ordinary pages.** It is a
+second, optional entry point — a passive inline status pill that opens the
+*same* global panel — for a spot where a deliberate, in-content link to
+personalization settings makes sense (a privacy or preferences page). It
+carries no opt-out controls of its own; switching audience and opting out
+always happen in the one global panel, never in two places that could
+disagree. Placing it on every page is redundant with the surface that's
+already there automatically.
+`personalization.transparencyNotice.enabled: false` (theme config) suppresses
+the automatic panel from appearing on its own; the badge (or the panel's own
+programmatic open) still works as a deliberate opt-in path.
+### Self-ID widget: all six display modes
+The self-ID widget (Admin → Audiences) is authorable in six display modes:
+`modal`, `inline`, `slide-in`, `hello_bar_top`, `hello_bar_bottom`, and
+`drawer`. For `inline`, the client runtime mounts the widget into an element
+matching `[data-kywi-selfid-mount]` when the page provides one; otherwise it
+appends to the end of `<body>`. Give an inline placement its own mount point
+when you want the widget to sit in a specific spot in the page flow rather
+than wherever the runtime defaults to.
 ## 9. Editorial workflow: drafts, review, versions
 For any site with more than one author — or an owner who wants a safety net —

package/assets/kywi-custom-modules-skill.md CHANGED Viewed

@@ -53,7 +53,8 @@ it — then pick the type:
 | `image` / `file` | media picker | anything from the Media library |
 | `boolean` | checkbox | layout flips (`reverse`), show/hide |
 | `number` / `date` / `color` | native inputs | counts, deadlines, accents |
-| `select` / `slug` / `relationship` | plain text input (today) | constrained values — name the options in the label |
+| `select` / `multiSelect` | dropdown / checkbox group (needs `options`) | closed choices — declare `options: [{ value, label }, …]` (bare strings also work) per prop |
+| `slug` / `relationship` | plain text input | constrained values with no options field yet — name the allowed values in the label |
 | `json` | raw JSON textarea | **developer territory** — structure the owner never edits |
 Two rules that decide whether the module is really editable:
@@ -84,6 +85,15 @@ export default defineKywiConfig({
         body: { type: 'richText', label: 'Body' },
         image: { type: 'image', label: 'Image' },
         imageAlt: { type: 'text', label: 'Image alt text' },
+        layout: {
+          type: 'select',
+          label: 'Layout',
+          options: [
+            { value: 'split', label: 'Media / text split' },
+            { value: 'stacked', label: 'Stacked' },
+          ],
+          defaultValue: 'split',
+        },                                                  // closed choice = real dropdown
         reverse: { type: 'boolean', label: 'Image on the left', defaultValue: false },
       },
     }),

package/lib/templates.mjs CHANGED Viewed

@@ -779,6 +779,20 @@ export function clientRuntimeEnabled(): boolean {
   return theme?.personalization?.clientRuntime === true
 }
+/**
+ * Is the global transparency surface (the automatic pill/panel showing which
+ * audience the page was personalized for, with a switcher and opt-out) enabled
+ * for this site's theme? \`personalization.transparencyNotice.enabled\` — unset
+ * defaults to true; only an explicit \`false\` suppresses the surface from
+ * appearing on its own. Even then a \`personalizationBadge\` module can still
+ * open it deliberately.
+ */
+export function transparencyNoticeEnabled(): boolean {
+  const themeName = config.sites[0]?.theme
+  const theme = config.themes.find((t) => t.name === themeName) ?? config.themes[0]
+  return theme?.personalization?.transparencyNotice?.enabled !== false
+}
 // ─── Self-ID widget (#50) ────────────────────────────────────────────────────
 /** The self-ID widget config in the serializable shape the client runtime reads. */
@@ -1236,6 +1250,7 @@ import {
   personalizeLayout,
   resolveSelfIdWidget,
   clientRuntimeEnabled,
+  transparencyNoticeEnabled,
   buildFeedResolver,
   buildComponentResolver,
   buildSectionComponentResolver,
@@ -1368,6 +1383,7 @@ export default async function PublicPage({ params, searchParams }: Params & Sear
           audiences={perso.audiences}
           serverSignals={perso.signals}
           selfIdWidget={selfIdWidget}
+          transparencyNotice={transparencyNoticeEnabled()}
         />
       ) : null}
     </>
@@ -1696,6 +1712,12 @@ interface PersonalizationRuntimeProps {
   serverSignals: Partial<VisitorSignals>
   /** Resolved self-ID widget config; when present its trigger/frequency mount it. */
   selfIdWidget?: PublicSelfIdWidget | null
+  /**
+   * \`personalization.transparencyNotice.enabled\` — false suppresses the
+   * automatic global transparency panel; the visitor can still open it
+   * deliberately through a \`personalizationBadge\` module. Defaults to true.
+   */
+  transparencyNotice?: boolean
 }
 /**
@@ -1704,7 +1726,7 @@ interface PersonalizationRuntimeProps {
  * experience, so opt-out is respected end to end. Rendered only when
  * theme.personalization.clientRuntime is on.
  */
-export function PersonalizationRuntime({ audiences, serverSignals, selfIdWidget }: PersonalizationRuntimeProps) {
+export function PersonalizationRuntime({ audiences, serverSignals, selfIdWidget, transparencyNotice }: PersonalizationRuntimeProps) {
   useEffect(() => {
     let cancelled = false
     const ready = () => typeof window.Kywi?.bootAudienceEngine === 'function'
@@ -1720,6 +1742,7 @@ export function PersonalizationRuntime({ audiences, serverSignals, selfIdWidget
           ...(selfIdWidget
             ? { selfIdWidget: { ...selfIdWidget, audiences, currentPath } }
             : {}),
+          ...(transparencyNotice === false ? { transparencyNotice: false } : {}),
         })
         .catch(() => {
           /* client personalization is best-effort; the server already rendered defaults */

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "create-kywi-app",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Scaffold a new Kywi CMS project — npx create-kywi-app my-site",
   "type": "module",
   "homepage": "https://github.com/Kywi-Software/kywi-cms#readme",