@pantheon-systems/puck-css 0.8.0 → 0.9.0

package/dist/editor/plugin/createP1Overrides.js

@@ -1,12 +1,22 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { ActionBar } from '@puckeditor/core';
+/**
+ * P1 Puck Overrides
+ *
+ * Creates Puck overrides for P1 integration, including
+ * header actions for save status and publish functionality.
+ */
+import React from 'react';
+import { ActionBar, FieldLabel } from '@puckeditor/core';
 import { SaveIndicator } from '../components/SaveIndicator.js';
-import { HistoricalVersionBanner } from '../../versioning/components/HistoricalVersionBanner.js';
 import { CollaboratorAvatars } from '../../collaboration/components/CollaboratorAvatars.js';
 import { AgentActivityBanner } from '../../collaboration/components/AgentActivityBanner.js';
 import { PublishedStatusBadge } from '../components/PublishedStatusBadge.js';
 import { ActionBarPinButton } from '../../features/content-type-templates/ui/ActionBarPinButton.js';
 import { P1InspectorFields } from '../components/P1InspectorFields.js';
+import { CollapsibleFieldSection } from '../components/CollapsibleFieldSection.js';
+import { CollapsibleFieldContext } from '../components/collapsibleSectionContext.js';
+import { OutlinePanel } from '../components/OutlinePanel.js';
+import { fieldGuidanceFieldTypes } from './fieldGuidance.js';
 // NOTE: PuckDataSynchronizer is NOT imported here - it's used in P1Plugin instead
 // because headerActions renders outside Puck's context where usePuck() doesn't work.
 // Re-exported for backwards compatibility — implementation lives in utils/templatePath.ts.
@@ -14,46 +24,26 @@ export { templateFromRegistryPath } from '../utils/templatePath.js';
 // Re-exported for backwards compatibility — implementation lives in components/P1TemplateFields.tsx.
 export { P1TemplateFields } from '../components/P1TemplateFields.js';
 /**
- * Creates Puck overrides for P1 integration.
- *
- * Adds SaveIndicator and PublishButton to the header actions area.
- *
- * @example
- * ```tsx
- * import { createP1Overrides, useP1Puck } from '@pantheon-systems/puck-css';
+ * Renders an opted-in field group's label row as a disclosure. Puck hands a
+ * label override the field's content as `children`, so the group's own label
+ * becomes the toggle — there is no second header and nothing to suppress.
  *
- * function Editor() {
- *   const {
- *     saveStatus,
- *     lastSaved,
- *     saveError,
- *     saveNow,
- *     publishDocument,
- *   } = useP1Puck();
+ * The context is cleared for descendants so a nested group inside a collapsible
+ * one keeps its ordinary label.
  *
- *   // Preferred: use refs and getters for better performance
- *   const saveStatusRef = useRef(saveStatus);
- *   useEffect(() => { saveStatusRef.current = saveStatus; }, [saveStatus]);
- *
- *   const overrides = createP1Overrides({
- *     getSaveStatus: () => saveStatusRef.current,
- *     getLastSaved: () => lastSavedRef.current,
- *     getSaveError: () => saveErrorRef.current,
- *     onRetrySave: saveNow,
- *   });
- *
- *   // Legacy: direct values (causes overrides to be recreated on changes)
- *   const overrides = createP1Overrides({
- *     saveStatus,
- *     lastSaved,
- *     saveError,
- *     onRetrySave: saveNow,
- *   });
- *
- *   return <Puck overrides={overrides} {...otherProps} />;
- * }
- * ```
+ * Ordinary field labels drop Puck's field-type icon. Its select variant is a
+ * chevron, the same glyph the disclosure above uses, so it reads as a group that
+ * expands and then does nothing. The label already says what the field is, and
+ * the narrow inspector would rather have the space. The read-only lock is a
+ * separate slot and survives.
  */
+export function P1FieldLabel(props) {
+    const collapsible = React.useContext(CollapsibleFieldContext);
+    if (collapsible && props.el === 'div') {
+        return (_jsx(CollapsibleFieldContext.Provider, { value: null, children: _jsx(CollapsibleFieldSection, { label: props.label, defaultCollapsed: collapsible.defaultCollapsed, count: collapsible.count, children: props.children }) }));
+    }
+    return _jsx(FieldLabel, { ...props, icon: undefined });
+}
 export function createP1Overrides(options) {
     const { 
     // New getter-based API (preferred)
@@ -63,7 +53,7 @@ export function createP1Overrides(options) {
     // Common options
     onRetrySave, showDefaultPublish = false, 
     // Deprecated props - kept for type signature compatibility but ignored
-    syncData: _syncData, dataSyncKey: _dataSyncKey,
+    syncData: _syncData, dataSyncKey: _dataSyncKey, onRestoreVersion: _onRestoreVersion, canRevert: _canRevert,
     // Presence/Agent Features — NOT destructured here.
     // These are read lazily from `options` in the headerActions render function
     // so that the Proxy pattern from useP1Overrides provides live values.
@@ -72,6 +62,8 @@ export function createP1Overrides(options) {
     // Suppress unused variable warnings for deprecated props
     void _syncData;
     void _dataSyncKey;
+    void _onRestoreVersion;
+    void _canRevert;
     // Determine if using getter API or direct props API
     const usingGetters = typeof getSaveStatus === 'function';
     // Build props for SaveIndicator based on which API is being used
@@ -91,6 +83,20 @@ export function createP1Overrides(options) {
     return {
         actionBar: ({ label, children }) => (_jsxs(ActionBar, { label: label, children: [children, _jsx(ActionBarPinButton, {})] })),
         fields: ({ children }) => (_jsx(P1InspectorFields, { children: children })),
+        fieldLabel: P1FieldLabel,
+        fieldTypes: {
+            ...fieldGuidanceFieldTypes,
+            // Marks an opted-in object field for P1FieldLabel, which owns the rendering
+            // because it is the only override that receives the label. Object fields
+            // without `metadata.collapsible` pass through untouched.
+            object: ({ field, children, }) => field.metadata?.collapsible ? (_jsx(CollapsibleFieldContext.Provider, { value: {
+                    defaultCollapsed: field.metadata.defaultCollapsed,
+                    // Derived from the resolved field set, so omitting a field — how
+                    // role gating will hide one — moves the count with it.
+                    count: Object.keys(field.objectFields ?? {}).length,
+                }, children: children })) : (_jsx(_Fragment, { children: children })),
+        },
+        outline: () => _jsx(OutlinePanel, {}),
         headerActions: ({ children }) => {
             // Read presence/agent values lazily from options (Proxy) each render
             // so they reflect the latest state from useP1Overrides' optionsRef.
@@ -102,12 +108,10 @@ export function createP1Overrides(options) {
             const _onStopAgent = options.onStopAgent;
             const _showSaveIndicator = options.showSaveIndicator ?? true;
             const _isViewingHistoricalVersion = options.isViewingHistoricalVersion ?? false;
-            const _viewingVersion = options.viewingVersion;
-            const _onReturnToLatest = options.onReturnToLatest;
             const _publishedStatus = options.publishedStatus;
             // Find the first active agent for banner display
             const firstActiveAgent = _activeAgents.find(a => a.state === 'editing') || _activeAgents[0];
-            return (_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: '8px' }, children: [_showAgentActivityBanner && _isAgentEditing && firstActiveAgent && (_jsx(AgentActivityBanner, { agent: firstActiveAgent, showIdle: true, onStopAgent: _onStopAgent })), _showCollaboratorAvatars && _presence.length > 0 && (_jsx(CollaboratorAvatars, { actors: _presence, maxVisible: 5 })), _isViewingHistoricalVersion && _viewingVersion && _onReturnToLatest ? (_jsx(HistoricalVersionBanner, { version: _viewingVersion, onReturnToLatest: _onReturnToLatest })) : (_jsxs(_Fragment, { children: [_showSaveIndicator && _jsx(SaveIndicator, { ...saveIndicatorProps }), _publishedStatus && (_jsx(PublishedStatusBadge, { status: _publishedStatus }))] })), showDefaultPublish && children] }));
+            return (_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: '8px' }, children: [_showAgentActivityBanner && _isAgentEditing && firstActiveAgent && (_jsx(AgentActivityBanner, { agent: firstActiveAgent, showIdle: true, onStopAgent: _onStopAgent })), _showCollaboratorAvatars && _presence.length > 0 && (_jsx(CollaboratorAvatars, { actors: _presence, maxVisible: 5 })), !_isViewingHistoricalVersion && (_jsxs(_Fragment, { children: [_showSaveIndicator && _jsx(SaveIndicator, { ...saveIndicatorProps }), _publishedStatus && (_jsx(PublishedStatusBadge, { status: _publishedStatus }))] })), showDefaultPublish && children] }));
         },
     };
 }

package/dist/editor/plugin/createP1Overrides.js.map

@@ -1 +1 @@
-{"version":3,"file":"createP1Overrides.js","sourceRoot":"","sources":["../../../src/editor/plugin/createP1Overrides.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"createP1Overrides.js","sourceRoot":"","sources":["../../../src/editor/plugin/createP1Overrides.tsx"],"names":[],"mappings":"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"}

package/dist/editor/plugin/fieldGuidance.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-field help text, rendered under the input.
+ *
+ * Opt in with Puck's per-field `metadata`, the same extension point the
+ * collapsible section uses:
+ *
+ *   metadata: { help: 'Always shown.', helpWhenEmpty: 'Shown while empty.' }
+ *
+ * `helpWhenEmpty` is how an inheriting field says where its value comes from,
+ * since a field is inheriting exactly while it is empty. Fields without either
+ * key render unchanged.
+ *
+ * These are `fieldTypes` overrides, so Puck hands us its own field renderer as
+ * `children` — the help is appended after it rather than replacing it. Note the
+ * side effect of registering a type here: Puck subscribes to the value of every
+ * field of that type, which is what makes the empty/authored switch work.
+ */
+import React from 'react';
+export interface FieldGuidanceMetadata {
+    help?: string;
+    helpWhenEmpty?: string;
+}
+interface GuidedFieldProps {
+    field: {
+        metadata?: FieldGuidanceMetadata;
+    };
+    value: unknown;
+    children: React.ReactNode;
+}
+declare function WithHelpText({ field, value, children }: GuidedFieldProps): React.ReactElement;
+/**
+ * The field types help text is wired for. Select is included for the fields
+ * whose fallback is a fixed default rather than another prop — it has no
+ * `placeholder` to show one in, so the help line carries it alone.
+ */
+export declare const fieldGuidanceFieldTypes: {
+    text: typeof WithHelpText;
+    textarea: typeof WithHelpText;
+    select: typeof WithHelpText;
+};
+export declare function createFieldGuidanceOverrides(): {
+    fieldTypes: typeof fieldGuidanceFieldTypes;
+};
+export {};
+//# sourceMappingURL=fieldGuidance.d.ts.map

package/dist/editor/plugin/fieldGuidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldGuidance.d.ts","sourceRoot":"","sources":["../../../src/editor/plugin/fieldGuidance.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,gBAAgB;IACxB,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,qBAAqB,CAAA;KAAE,CAAC;IAC5C,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,iBAAS,YAAY,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,gBAAgB,GAAG,KAAK,CAAC,YAAY,CActF;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;CAInC,CAAC;AAEF,wBAAgB,4BAA4B,IAAI;IAC9C,UAAU,EAAE,OAAO,uBAAuB,CAAC;CAC5C,CAEA"}

package/dist/editor/plugin/fieldGuidance.js

@@ -0,0 +1,24 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { FieldHelpText } from '../components/FieldHelpText.js';
+function WithHelpText({ field, value, children }) {
+    const { help, helpWhenEmpty } = field.metadata ?? {};
+    const text = value === undefined || value === null || value === '' ? helpWhenEmpty ?? help : help;
+    if (!text) {
+        return _jsx(_Fragment, { children: children });
+    }
+    return (_jsxs(_Fragment, { children: [children, _jsx(FieldHelpText, { children: text })] }));
+}
+/**
+ * The field types help text is wired for. Select is included for the fields
+ * whose fallback is a fixed default rather than another prop — it has no
+ * `placeholder` to show one in, so the help line carries it alone.
+ */
+export const fieldGuidanceFieldTypes = {
+    text: WithHelpText,
+    textarea: WithHelpText,
+    select: WithHelpText,
+};
+export function createFieldGuidanceOverrides() {
+    return { fieldTypes: fieldGuidanceFieldTypes };
+}
+//# sourceMappingURL=fieldGuidance.js.map

package/dist/editor/plugin/fieldGuidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldGuidance.js","sourceRoot":"","sources":["../../../src/editor/plugin/fieldGuidance.tsx"],"names":[],"mappings":";AAmBA,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAa/D,SAAS,YAAY,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAoB;IAChE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;IACrD,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAElG,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,4BAAG,QAAQ,GAAI,CAAC;IACzB,CAAC;IAED,OAAO,CACL,8BACG,QAAQ,EACT,KAAC,aAAa,cAAE,IAAI,GAAiB,IACpC,CACJ,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,IAAI,EAAE,YAAY;IAClB,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,YAAY;CACrB,CAAC;AAEF,MAAM,UAAU,4BAA4B;IAG1C,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,CAAC;AACjD,CAAC"}

package/dist/editor/plugin/mergePreviewPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mergePreviewPlugin.d.ts","sourceRoot":"","sources":["../../../src/editor/plugin/mergePreviewPlugin.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKhD,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IAEnD,MAAM,EAAE,GAAG,CAAC;IAEZ,4CAA4C;IAC5C,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CACjD;AAyDD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GACjC,UAAU,CAYZ"}
+{"version":3,"file":"mergePreviewPlugin.d.ts","sourceRoot":"","sources":["../../../src/editor/plugin/mergePreviewPlugin.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IAEnD,MAAM,EAAE,GAAG,CAAC;IAEZ,4CAA4C;IAC5C,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CACjD;AAyDD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GACjC,UAAU,CAYZ"}

package/dist/editor/plugin/mergePreviewPlugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"mergePreviewPlugin.js","sourceRoot":"","sources":["../../../src/editor/plugin/mergePreviewPlugin.tsx"],"names":[],"mappings":";AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kDAAkD,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAiBhE,SAAS,0BAA0B,CAAC,EAClC,MAAM,EACN,gBAAgB,GACgB;IAChC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,YAAY,EAAE,GACnF,eAAe,EAAE,CAAC;IAEpB,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,CACL,eAAK,SAAS,EAAC,qBAAqB,aAClC,aAAI,SAAS,EAAC,4BAA4B,8BAAmB,EAC7D,YAAG,SAAS,EAAC,4BAA4B,0EAErC,IACA,CACP,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CACL,eAAK,SAAS,EAAC,qBAAqB,aAClC,aAAI,SAAS,EAAC,4BAA4B,8BAAmB,EAC7D,YAAG,SAAS,EAAC,8BAA8B,yCAAwB,IAC/D,CACP,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CACL,eAAK,SAAS,EAAC,qBAAqB,aAClC,aAAI,SAAS,EAAC,4BAA4B,8BAAmB,EAC7D,aAAG,SAAS,EAAC,4BAA4B,4CACX,KAAK,CAAC,OAAO,IACvC,IACA,CACP,CAAC;IACJ,CAAC;IAED,OAAO,CACL,KAAC,iBAAiB,IAChB,SAAS,EAAE,SAAS,EACpB,gBAAgB,EAAE,gBAAgB,EAClC,gBAAgB,EAAE,gBAAgB,EAClC,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,gBAAgB,GAClC,CACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,OAAkC;IAElC,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,KAAC,gBAAgB,KAAG;QAC1B,MAAM,EAAE,GAAG,EAAE,CAAC,CACZ,KAAC,0BAA0B,IACzB,MAAM,EAAE,OAAO,CAAC,MAAM,EACtB,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,GAC1C,CACH;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"mergePreviewPlugin.js","sourceRoot":"","sources":["../../../src/editor/plugin/mergePreviewPlugin.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kDAAkD,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAkBhE,SAAS,0BAA0B,CAAC,EAClC,MAAM,EACN,gBAAgB,GACgB;IAChC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,YAAY,EAAE,GACnF,eAAe,EAAE,CAAC;IAEpB,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,CACL,eAAK,SAAS,EAAC,qBAAqB,aAClC,aAAI,SAAS,EAAC,4BAA4B,8BAAmB,EAC7D,YAAG,SAAS,EAAC,4BAA4B,0EAErC,IACA,CACP,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CACL,eAAK,SAAS,EAAC,qBAAqB,aAClC,aAAI,SAAS,EAAC,4BAA4B,8BAAmB,EAC7D,YAAG,SAAS,EAAC,8BAA8B,yCAAwB,IAC/D,CACP,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CACL,eAAK,SAAS,EAAC,qBAAqB,aAClC,aAAI,SAAS,EAAC,4BAA4B,8BAAmB,EAC7D,aAAG,SAAS,EAAC,4BAA4B,4CACX,KAAK,CAAC,OAAO,IACvC,IACA,CACP,CAAC;IACJ,CAAC;IAED,OAAO,CACL,KAAC,iBAAiB,IAChB,SAAS,EAAE,SAAS,EACpB,gBAAgB,EAAE,gBAAgB,EAClC,gBAAgB,EAAE,gBAAgB,EAClC,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,gBAAgB,GAClC,CACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,OAAkC;IAElC,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,KAAC,gBAAgB,KAAG;QAC1B,MAAM,EAAE,GAAG,EAAE,CAAC,CACZ,KAAC,0BAA0B,IACzB,MAAM,EAAE,OAAO,CAAC,MAAM,EACtB,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,GAC1C,CACH;KACF,CAAC;AACJ,CAAC"}

package/dist/editor/plugin/selectHeaderCollaborators.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Selects the human collaborators shown as avatars in the editor header.
+ *
+ * Agents are deliberately excluded — they render as chips in the subheader.
+ *
+ */
+import type { ActorPresence } from '@pantheon-systems/css-client';
+export interface HeaderPresenceState {
+    humans?: ActorPresence[];
+}
+export declare function selectHeaderCollaborators(presence: HeaderPresenceState | null | undefined, _hasActiveHumans: boolean, humanPresenceCount: number): ActorPresence[];
+//# sourceMappingURL=selectHeaderCollaborators.d.ts.map

package/dist/editor/plugin/selectHeaderCollaborators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectHeaderCollaborators.d.ts","sourceRoot":"","sources":["../../../src/editor/plugin/selectHeaderCollaborators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,EAChD,gBAAgB,EAAE,OAAO,EACzB,kBAAkB,EAAE,MAAM,GACzB,aAAa,EAAE,CAMjB"}

package/dist/editor/plugin/selectHeaderCollaborators.js

@@ -0,0 +1,15 @@
+/**
+ * Selects the human collaborators shown as avatars in the editor header.
+ *
+ * Agents are deliberately excluded — they render as chips in the subheader.
+ *
+ */
+export function selectHeaderCollaborators(presence, _hasActiveHumans, humanPresenceCount) {
+    const humans = presence?.humans ?? [];
+    // humanPresenceCount is the fresher of the two signals on a mid-session
+    // departure, so it still guards against a stale presence getter.
+    if (humanPresenceCount <= 0 || humans.length === 0)
+        return [];
+    return humans;
+}
+//# sourceMappingURL=selectHeaderCollaborators.js.map

package/dist/editor/plugin/selectHeaderCollaborators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectHeaderCollaborators.js","sourceRoot":"","sources":["../../../src/editor/plugin/selectHeaderCollaborators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,UAAU,yBAAyB,CACvC,QAAgD,EAChD,gBAAyB,EACzB,kBAA0B;IAE1B,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;IACtC,wEAAwE;IACxE,iEAAiE;IACjE,IAAI,kBAAkB,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9D,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/editor/thumbnails/LiveThumbnail.d.ts

@@ -0,0 +1,47 @@
+/**
+ * LiveThumbnail
+ *
+ * Renders a real, scaled-down preview of a single Puck component using the
+ * component's own `defaultProps`, via Puck's <Render>. The preview is clipped
+ * to a fixed height and made non-interactive so it reads as a static thumbnail
+ * inside the visual component sidebar.
+ *
+ * Rendering is cached (see thumbnailCache): on a miss we render live and
+ * capture the resulting HTML; on a hit we re-inject the cached HTML instead of
+ * re-rendering the component. The cache survives editor remounts within a
+ * page load, avoiding re-rendering identical previews on every document
+ * switch.
+ *
+ * The initial capture happens right after the component's first commit, but a
+ * component that renders its own content asynchronously (e.g. after a fetch,
+ * in its own effect) may still be showing a loading state at that point. A
+ * MutationObserver keeps watching the live render and re-captures on every
+ * DOM change, so the cache converges on the settled output instead of
+ * permanently freezing whatever was on screen first.
+ *
+ * The config handed to Puck's <Render> has its `root` swapped for a
+ * pass-through: this preview is a single component, not a page, so it must
+ * not run the site's real page-root wrapper (e.g. a title `<h1>`) — that
+ * wrapper reflects the actual document currently open in the editor, not
+ * this isolated stub, and would otherwise leak into every preview.
+ *
+ * Unlike the exploratory spike this does NOT self-measure its height — grid
+ * cards want a uniform, fixed size, so we clip overflow instead.
+ */
+import React from 'react';
+type RenderConfig = any;
+export interface LiveThumbnailProps {
+    /** The Puck config the component belongs to. */
+    config: RenderConfig;
+    /** Component key to preview (e.g. "HeroBlock"). */
+    name: string;
+    /** Zoom factor applied to the live render. Lower = more fits. */
+    scale?: number;
+    /** Fixed height of the clipped preview box, in pixels. */
+    height?: number;
+}
+declare function LiveThumbnailImpl({ config, name, scale, height }: LiveThumbnailProps): React.JSX.Element;
+/** Memoized so re-expanding a category doesn't re-render existing previews. */
+export declare const LiveThumbnail: React.MemoExoticComponent<typeof LiveThumbnailImpl>;
+export {};
+//# sourceMappingURL=LiveThumbnail.d.ts.map

package/dist/editor/thumbnails/LiveThumbnail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LiveThumbnail.d.ts","sourceRoot":"","sources":["../../../src/editor/thumbnails/LiveThumbnail.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B,KAAK,YAAY,GAAG,GAAG,CAAC;AAExB,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,MAAM,EAAE,YAAY,CAAC;IACrB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,iBAAS,iBAAiB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,KAAW,EAAE,MAAiC,EAAE,EAAE,kBAAkB,qBAiG9G;AAED,+EAA+E;AAC/E,eAAO,MAAM,aAAa,qDAAgC,CAAC"}

package/dist/editor/thumbnails/LiveThumbnail.js

@@ -0,0 +1,120 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * LiveThumbnail
+ *
+ * Renders a real, scaled-down preview of a single Puck component using the
+ * component's own `defaultProps`, via Puck's <Render>. The preview is clipped
+ * to a fixed height and made non-interactive so it reads as a static thumbnail
+ * inside the visual component sidebar.
+ *
+ * Rendering is cached (see thumbnailCache): on a miss we render live and
+ * capture the resulting HTML; on a hit we re-inject the cached HTML instead of
+ * re-rendering the component. The cache survives editor remounts within a
+ * page load, avoiding re-rendering identical previews on every document
+ * switch.
+ *
+ * The initial capture happens right after the component's first commit, but a
+ * component that renders its own content asynchronously (e.g. after a fetch,
+ * in its own effect) may still be showing a loading state at that point. A
+ * MutationObserver keeps watching the live render and re-captures on every
+ * DOM change, so the cache converges on the settled output instead of
+ * permanently freezing whatever was on screen first.
+ *
+ * The config handed to Puck's <Render> has its `root` swapped for a
+ * pass-through: this preview is a single component, not a page, so it must
+ * not run the site's real page-root wrapper (e.g. a title `<h1>`) — that
+ * wrapper reflects the actual document currently open in the editor, not
+ * this isolated stub, and would otherwise leak into every preview.
+ *
+ * Unlike the exploratory spike this does NOT self-measure its height — grid
+ * cards want a uniform, fixed size, so we clip overflow instead.
+ */
+import React from 'react';
+import { Render } from '@puckeditor/core';
+import { getCachedThumbnail, setCachedThumbnail, getThumbnailCacheKey } from './thumbnailCache.js';
+import { DEFAULT_THUMBNAIL_HEIGHT } from './ThumbnailCard.js';
+function LiveThumbnailImpl({ config, name, scale = 0.2, height = DEFAULT_THUMBNAIL_HEIGHT }) {
+    const defaultProps = config?.components?.[name]?.defaultProps ?? {};
+    const cacheKey = getThumbnailCacheKey(config, name);
+    // Read once at mount: a hit lets us skip the live render entirely.
+    const [cached] = React.useState(() => getCachedThumbnail(cacheKey));
+    const innerRef = React.useRef(null);
+    // Isolated document: this preview is the one component, not a page — the
+    // real root wrapper is swapped for a pass-through below.
+    const data = {
+        root: { props: {} },
+        content: [
+            {
+                type: name,
+                props: { id: `thumb-${name}`, ...defaultProps },
+            },
+        ],
+        zones: {},
+    };
+    const isolatedConfig = React.useMemo(() => ({ ...config, root: { render: ({ children }) => children } }), [config]);
+    // On a miss, capture the live-rendered HTML once it has committed, then
+    // keep re-capturing on any further mutation so a component that finishes
+    // rendering asynchronously (its own effect, a fetch, an image swap) doesn't
+    // get an incomplete snapshot cached permanently.
+    //
+    // Mutations are debounced through requestAnimationFrame so a burst of DOM
+    // changes (e.g. a component updating several nodes at once) produces one
+    // capture per frame. Attribute mutations are excluded — they fire continuously
+    // for animations and class toggles without changing rendered content.
+    // The observer disconnects after 500 ms of DOM quiet so it doesn't run for
+    // the drawer's entire lifetime.
+    React.useEffect(() => {
+        if (cached !== undefined)
+            return;
+        const node = innerRef.current;
+        if (!node)
+            return;
+        const capture = () => {
+            const html = node.innerHTML;
+            if (html)
+                setCachedThumbnail(cacheKey, html);
+        };
+        let rafId = null;
+        let settleTimer = null;
+        const onMutation = () => {
+            if (rafId !== null)
+                cancelAnimationFrame(rafId);
+            rafId = requestAnimationFrame(() => {
+                capture();
+                rafId = null;
+            });
+            if (settleTimer !== null)
+                clearTimeout(settleTimer);
+            settleTimer = setTimeout(() => observer.disconnect(), 500);
+        };
+        capture();
+        const observer = new MutationObserver(onMutation);
+        observer.observe(node, { childList: true, subtree: true, characterData: true });
+        return () => {
+            observer.disconnect();
+            if (rafId !== null)
+                cancelAnimationFrame(rafId);
+            if (settleTimer !== null)
+                clearTimeout(settleTimer);
+        };
+    }, [cached, cacheKey]);
+    const boxStyle = {
+        width: '100%',
+        height,
+        overflow: 'hidden',
+        background: '#fff',
+        pointerEvents: 'none',
+    };
+    const innerStyle = {
+        transform: `scale(${scale})`,
+        transformOrigin: 'top left',
+        width: `${100 / scale}%`,
+    };
+    return (_jsx("div", { style: boxStyle, children: cached !== undefined ? (
+        // Trusted source: this HTML was produced by our own <Render> of the
+        // component's defaultProps — never user input.
+        _jsx("div", { style: innerStyle, dangerouslySetInnerHTML: { __html: cached } })) : (_jsx("div", { style: innerStyle, ref: innerRef, children: _jsx(Render, { config: isolatedConfig, data: data }) })) }));
+}
+/** Memoized so re-expanding a category doesn't re-render existing previews. */
+export const LiveThumbnail = React.memo(LiveThumbnailImpl);
+//# sourceMappingURL=LiveThumbnail.js.map

package/dist/editor/thumbnails/LiveThumbnail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LiveThumbnail.js","sourceRoot":"","sources":["../../../src/editor/thumbnails/LiveThumbnail.tsx"],"names":[],"mappings":"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"}

package/dist/editor/thumbnails/ThumbnailCard.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ThumbnailCard
+ *
+ * One card in the visual component sidebar grid: a live preview above a
+ * centered, human-readable name.
+ *
+ * To keep opening a category feeling instant, the expensive live <Render> is
+ * NOT mounted on the first commit unless a preview is already cached.
+ * Otherwise, a lightweight skeleton paints immediately and the real preview
+ * is scheduled on idle time, then swapped in. The preview is wrapped in an
+ * error boundary so a single misbehaving component degrades to a placeholder
+ * rather than taking down the drawer.
+ *
+ * Seeding `ready` from the cache matters beyond the first paint: Puck's own
+ * <Drawer>/<Drawer.Item> primitives remount on unrelated editor state changes
+ * (e.g. typing in any field), which remounts every ThumbnailCard too. Without
+ * the cache check, `ready` would reset to false on every one of those
+ * remounts, flashing the skeleton back in even for previews already rendered.
+ */
+import React from 'react';
+type RenderConfig = any;
+/** Default preview-card height in pixels, shared across LiveThumbnail, ThumbnailCard, and the drawer. */
+export declare const DEFAULT_THUMBNAIL_HEIGHT = 96;
+export interface ThumbnailCardProps {
+    config: RenderConfig;
+    name: string;
+    /** Preferred display name; falls back to a humanized component key. */
+    label?: string;
+    scale?: number;
+    /** Fixed height of the preview area, in pixels. */
+    height?: number;
+}
+declare function ThumbnailCardImpl({ config, name, label, scale, height }: ThumbnailCardProps): React.JSX.Element;
+/** Memoized so a category re-expand keeps already-rendered cards mounted. */
+export declare const ThumbnailCard: React.MemoExoticComponent<typeof ThumbnailCardImpl>;
+export {};
+//# sourceMappingURL=ThumbnailCard.d.ts.map

package/dist/editor/thumbnails/ThumbnailCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThumbnailCard.d.ts","sourceRoot":"","sources":["../../../src/editor/thumbnails/ThumbnailCard.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAM1B,KAAK,YAAY,GAAG,GAAG,CAAC;AAExB,yGAAyG;AACzG,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAwED,iBAAS,iBAAiB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAiC,EAAE,EAAE,kBAAkB,qBA+B/G;AAED,6EAA6E;AAC7E,eAAO,MAAM,aAAa,qDAAgC,CAAC"}

package/dist/editor/thumbnails/ThumbnailCard.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ThumbnailCard
+ *
+ * One card in the visual component sidebar grid: a live preview above a
+ * centered, human-readable name.
+ *
+ * To keep opening a category feeling instant, the expensive live <Render> is
+ * NOT mounted on the first commit unless a preview is already cached.
+ * Otherwise, a lightweight skeleton paints immediately and the real preview
+ * is scheduled on idle time, then swapped in. The preview is wrapped in an
+ * error boundary so a single misbehaving component degrades to a placeholder
+ * rather than taking down the drawer.
+ *
+ * Seeding `ready` from the cache matters beyond the first paint: Puck's own
+ * <Drawer>/<Drawer.Item> primitives remount on unrelated editor state changes
+ * (e.g. typing in any field), which remounts every ThumbnailCard too. Without
+ * the cache check, `ready` would reset to false on every one of those
+ * remounts, flashing the skeleton back in even for previews already rendered.
+ */
+import React from 'react';
+import { LiveThumbnail } from './LiveThumbnail.js';
+import { humanizeComponentName } from './humanizeComponentName.js';
+import { getCachedThumbnail, getThumbnailCacheKey } from './thumbnailCache.js';
+/** Default preview-card height in pixels, shared across LiveThumbnail, ThumbnailCard, and the drawer. */
+export const DEFAULT_THUMBNAIL_HEIGHT = 96;
+// ─── Idle scheduling (with a jsdom/SSR-safe fallback) ───────────────────────
+function scheduleIdle(cb) {
+    const ric = globalThis.requestIdleCallback;
+    if (ric)
+        return ric(cb);
+    return setTimeout(cb, 1);
+}
+function cancelIdle(id) {
+    const cic = globalThis.cancelIdleCallback;
+    if (cic)
+        cic(id);
+    else
+        clearTimeout(id);
+}
+// ─── Error boundary ─────────────────────────────────────────────────────────
+class PreviewErrorBoundary extends React.Component {
+    state = { hasError: false };
+    static getDerivedStateFromError() {
+        return { hasError: true };
+    }
+    render() {
+        return this.state.hasError ? this.props.fallback : this.props.children;
+    }
+}
+// ─── Pieces ─────────────────────────────────────────────────────────────────
+function Skeleton({ height }) {
+    return (_jsx("div", { role: "status", "aria-label": "Loading preview", style: {
+            height,
+            background: 'linear-gradient(90deg, #f1f3f5 25%, #e9ecef 37%, #f1f3f5 63%)',
+            backgroundSize: '400% 100%',
+            animation: 'p1-thumb-shimmer 1.2s ease-in-out infinite',
+        } }));
+}
+function PreviewUnavailable({ height }) {
+    return (_jsx("div", { role: "img", "aria-label": "Preview unavailable", style: {
+            height,
+            display: 'grid',
+            placeItems: 'center',
+            background: '#f8f9fa',
+            color: '#adb5bd',
+            fontSize: 11,
+        }, children: "No preview" }));
+}
+// ─── Card ─────────────────────────────────────────────────────────────────────
+function ThumbnailCardImpl({ config, name, label, scale, height = DEFAULT_THUMBNAIL_HEIGHT }) {
+    const [ready, setReady] = React.useState(() => getCachedThumbnail(getThumbnailCacheKey(config, name)) !== undefined);
+    React.useEffect(() => {
+        if (ready)
+            return;
+        let cancelled = false;
+        const id = scheduleIdle(() => {
+            if (!cancelled)
+                setReady(true);
+        });
+        return () => {
+            cancelled = true;
+            cancelIdle(id);
+        };
+    }, [ready]);
+    const displayName = label ?? humanizeComponentName(name);
+    return (_jsxs("div", { className: "p1-thumb-card", children: [ready ? (_jsx(PreviewErrorBoundary, { fallback: _jsx(PreviewUnavailable, { height: height }), children: _jsx(LiveThumbnail, { config: config, name: name, scale: scale, height: height }) })) : (_jsx(Skeleton, { height: height })), _jsx("div", { className: "p1-thumb-card__label", title: displayName, children: displayName })] }));
+}
+/** Memoized so a category re-expand keeps already-rendered cards mounted. */
+export const ThumbnailCard = React.memo(ThumbnailCardImpl);
+//# sourceMappingURL=ThumbnailCard.js.map

package/dist/editor/thumbnails/ThumbnailCard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThumbnailCard.js","sourceRoot":"","sources":["../../../src/editor/thumbnails/ThumbnailCard.tsx"],"names":[],"mappings":"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"}