@picked/svelte 0.0.1-dev.1789541668638 → 0.0.1-dev.1793756239746

package/dist/plugins/devtools/launcher/Launcher.svelte

@@ -0,0 +1,150 @@
+<script lang="ts">
+  /** @file The floating Picked button that opens the devtools panel, in a chosen corner. */
+  import PickedIcon from '../PickedIcon.svelte'
+  import type { LauncherPosition } from '../options'
+  import { launcherEdges } from './launcher'
+
+  interface Props {
+    /** The corner the button sits in. */
+    position: LauncherPosition
+    /** When `true`, the button slides against its side edge until hovered or focused. */
+    autoHide: boolean
+    /** The tag beside the button: a preview session, a preview whose workspace is gone, or none. */
+    preview: 'preview' | 'unavailable' | null
+    /** Opens the panel. */
+    onOpen: () => void
+  }
+
+  const { position, autoHide, preview, onOpen }: Props = $props()
+
+  const edges = $derived(launcherEdges(position))
+</script>
+
+<div
+  class="launcher {edges.vertical} {edges.side}"
+  class:auto-hide={autoHide}
+  data-testid="devtools-launcher"
+  data-position={position}
+>
+  {#if preview === 'unavailable'}
+    <span
+      class="preview-tag preview-unavailable"
+      role="status"
+      aria-live="polite"
+      title="This preview link's workspace no longer exists. The published site is shown."
+    >Preview unavailable — showing published</span>
+  {:else if preview === 'preview'}
+    <span class="preview-tag" role="status" aria-live="polite">Preview mode</span>
+  {/if}
+  <button
+    class="floating-button"
+    class:has-preview-tag={preview !== null}
+    onclick={onOpen}
+    aria-label="Open Picked Devtools"
+    title="Open Picked Devtools"
+  >
+    <PickedIcon height={25} width={25} />
+  </button>
+</div>
+
+<style>
+  .launcher {
+    position: fixed;
+    z-index: 999999;
+    display: flex;
+    align-items: stretch;
+    cursor: pointer;
+    transition: transform 180ms ease-out;
+  }
+
+  .launcher.top {
+    top: calc(1rem + env(safe-area-inset-top, 0px));
+  }
+
+  .launcher.bottom {
+    bottom: calc(1rem + env(safe-area-inset-bottom, 0px));
+  }
+
+  .launcher.right {
+    right: env(safe-area-inset-right, 0px);
+  }
+
+  /* The button meets the edge it sits against, so the tag goes on its inner side. */
+  .launcher.left {
+    left: env(safe-area-inset-left, 0px);
+    flex-direction: row-reverse;
+  }
+
+  .launcher.auto-hide.right {
+    transform: translateX(calc(100% - 8px));
+  }
+
+  .launcher.auto-hide.left {
+    transform: translateX(calc(-100% + 8px));
+  }
+
+  .launcher.auto-hide:hover,
+  .launcher.auto-hide:focus-within {
+    transform: translateX(0);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .launcher {
+      transition: none;
+    }
+  }
+
+  .floating-button {
+    border-radius: 6px;
+    background-color: #ffffff;
+    display: grid;
+    place-items: center;
+    cursor: pointer;
+    border: 0 transparent;
+    padding: 6px;
+    box-shadow: 2px 2px 4px #00000029;
+
+    &:hover {
+      background-color: #f5f5f5;
+    }
+
+    &:focus-visible {
+      outline: 2px solid #3b82f6;
+      outline-offset: 2px;
+    }
+  }
+
+  .right .floating-button.has-preview-tag {
+    border-radius: 0 6px 6px 0;
+  }
+
+  .left .floating-button.has-preview-tag {
+    border-radius: 6px 0 0 6px;
+  }
+
+  .preview-tag {
+    display: flex;
+    align-items: center;
+    padding: 0 10px;
+    background: #2563eb;
+    color: #ffffff;
+    font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+      'Helvetica Neue', Arial, sans-serif;
+    font-size: 12px;
+    font-weight: 500;
+    line-height: 1.4;
+    box-shadow: 2px 2px 4px #00000029;
+  }
+
+  .right .preview-tag {
+    border-radius: 6px 0 0 6px;
+  }
+
+  .left .preview-tag {
+    border-radius: 0 6px 6px 0;
+  }
+
+  .preview-tag.preview-unavailable {
+    background: #b45309;
+  }
+</style>

package/dist/plugins/devtools/launcher/launcher.d.ts

@@ -0,0 +1,36 @@
+/** @file The floating devtools button's corner, and the viewer's remembered auto-hide choice. */
+import type { LauncherPosition } from '../options';
+/** `localStorage` key holding the viewer's auto-hide choice, `'true'` or `'false'`. */
+export declare const AUTO_HIDE_STORAGE_KEY = "picked-devtools-launcher-autohide";
+/** Reads the storage to use; may throw where site data is blocked. */
+export type StorageGetter = () => Pick<Storage, 'getItem' | 'setItem'>;
+/** The two edges a corner sits against. */
+export interface LauncherEdges {
+    vertical: 'top' | 'bottom';
+    side: 'left' | 'right';
+}
+/**
+ * Reads whether the button auto-hides: the viewer's stored choice, else the host's option.
+ *
+ * @param {StorageGetter} getStorage - Reads the storage holding the viewer's choice.
+ * @param {boolean} fallback - The host's `launcher.autoHide` option.
+ * @returns {boolean} `true` when the button tucks away until hovered or focused.
+ * @example readAutoHide(() => window.localStorage, true)
+ */
+export declare function readAutoHide(getStorage: StorageGetter, fallback: boolean): boolean;
+/**
+ * Stores the viewer's auto-hide choice. Does nothing where storage is denied.
+ *
+ * @param {StorageGetter} getStorage - Reads the storage to write to.
+ * @param {boolean} value - The viewer's choice.
+ * @example writeAutoHide(() => window.localStorage, false)
+ */
+export declare function writeAutoHide(getStorage: StorageGetter, value: boolean): void;
+/**
+ * Names the edges a corner sits against.
+ *
+ * @param {LauncherPosition} position - The corner.
+ * @returns {LauncherEdges} Its vertical and side edge.
+ * @example launcherEdges('top-left') // { vertical: 'top', side: 'left' }
+ */
+export declare function launcherEdges(position: LauncherPosition): LauncherEdges;

package/dist/plugins/devtools/launcher/launcher.js

@@ -0,0 +1 @@
+var e=`picked-devtools-launcher-autohide`;function t(t,n){try{let r=t().getItem(e);return r===`true`||r!==`false`&&n}catch{return n}}function n(t,n){try{t().setItem(e,String(n))}catch{}}function r(e){return{vertical:e.startsWith(`top`)?`top`:`bottom`,side:e.endsWith(`left`)?`left`:`right`}}export{e as AUTO_HIDE_STORAGE_KEY,r as launcherEdges,t as readAutoHide,n as writeAutoHide};

package/dist/plugins/devtools/options.d.ts

@@ -0,0 +1,106 @@
+/** @file The devtools plugin's options, and how the devtools panel reads them back off the client. */
+import type { Picked } from '@picked/client';
+export { DEVTOOLS_EXPERIENCE_KEY } from './constants';
+/** The corner the floating devtools button sits in. */
+export type LauncherPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/** Where the floating devtools button sits and whether it tucks away until hovered. */
+export interface LauncherOptions {
+    /**
+     * The corner the button sits in.
+     *
+     * @default 'bottom-right'
+     */
+    position?: LauncherPosition;
+    /**
+     * When `true`, the button slides against its side edge until hovered or focused. A viewer's own
+     * choice from the panel header takes precedence.
+     *
+     * @default true
+     */
+    autoHide?: boolean;
+}
+/** A button the Answers tab shows after an answer is edited. */
+export interface AnswerFollowUp {
+    /** The button's text. */
+    label: string;
+    /** Runs when the button is pressed. */
+    run: (client: Picked) => void;
+}
+/** A How to use section supplied by the host, for a feature that is not a devtools tab. */
+export interface DevtoolsGuideSection {
+    /** Unique within the guide. */
+    id: string;
+    /** The section heading. */
+    title: string;
+    /** Numbered steps, in order. `**text**` marks a control's label. */
+    steps: readonly string[];
+    /** Short lines after the steps. */
+    notes?: readonly string[];
+}
+/** A "something is not working" entry in How to use. */
+export interface DevtoolsGuideFix {
+    /** What the viewer sees. */
+    problem: string;
+    /** What to do about it. */
+    fix: string;
+}
+/** Host-supplied How to use content, listed before the devtools' own sections. */
+export interface DevtoolsGuide {
+    sections?: readonly DevtoolsGuideSection[];
+    fixes?: readonly DevtoolsGuideFix[];
+}
+/** The options read by the devtools panel, as passed to `svelteDevtoolsPlugin`. */
+export interface DevtoolsPanelOptions {
+    /**
+     * When `true`, the panel withholds every write — answer edits, clears and resets, journey jumps —
+     * and says why. For a session that may belong to a real visitor, such as a preview link opened
+     * on a live site. A preview token alone never makes a session read-only.
+     *
+     * @default false
+     */
+    readOnly?: boolean;
+    /** The environment's name, shown as a badge in the panel header. */
+    environmentLabel?: string;
+    /** Experience keys the journey views never list or follow, such as a host's own internal widgets. */
+    hiddenExperienceKeys?: readonly string[];
+    /**
+     * Experience keys, topmost first. When several experiences are open, the first one listed here
+     * is the journey the panel follows. Unlisted ones follow the most recently opened.
+     */
+    journeyPrecedence?: readonly string[];
+    /** Field keys committed by code rather than answered by the visitor; Answers leaves them out. */
+    codeOwnedFields?: readonly string[];
+    /** A button the Answers tab offers after an edit, such as re-running a fetch the answers feed. */
+    answerFollowUp?: AnswerFollowUp;
+    /** How to use content for host features that are not devtools tabs. */
+    guide?: DevtoolsGuide;
+    /** The floating button's corner and auto-hide. */
+    launcher?: LauncherOptions;
+}
+/** The devtools options with every default applied. */
+export interface ResolvedDevtoolsOptions {
+    readOnly: boolean;
+    environmentLabel: string | undefined;
+    /** Always includes the devtools experience itself. */
+    hiddenExperienceKeys: ReadonlySet<string>;
+    journeyPrecedence: readonly string[];
+    codeOwnedFields: ReadonlySet<string>;
+    answerFollowUp: AnswerFollowUp | null;
+    guide: {
+        sections: Required<DevtoolsGuideSection>[];
+        fixes: DevtoolsGuideFix[];
+    };
+    launcher: Required<LauncherOptions>;
+}
+/** Every corner the floating button can sit in. */
+export declare const LAUNCHER_POSITIONS: readonly LauncherPosition[];
+/**
+ * Reads the devtools options off the client's plugin config, applying every default. A malformed
+ * option falls back to its default, so one bad value never stops the panel rendering.
+ *
+ * @param {Pick<Picked, 'getPluginConfig'>} client - The client the devtools plugin is registered on.
+ * @returns {ResolvedDevtoolsOptions} The options with defaults applied.
+ * @example
+ * const { readOnly, launcher } = readDevtoolsOptions(getPicked())
+ */
+export declare function readDevtoolsOptions(client: Pick<Picked, 'getPluginConfig'>): ResolvedDevtoolsOptions;

package/dist/plugins/devtools/options.js

@@ -0,0 +1 @@
+import{DEVTOOLS_EXPERIENCE_KEY as e,DEVTOOLS_PLUGIN_NAME as t}from"./constants.js";var n=[`top-left`,`top-right`,`bottom-left`,`bottom-right`];function r(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function i(e){return Array.isArray(e)?e.filter(e=>typeof e==`string`):[]}function a(e){return n.some(t=>t===e)}function o(e){if(!r(e))return null;let{id:t,title:n,steps:a,notes:o}=e;return typeof t!=`string`||typeof n!=`string`||!Array.isArray(a)?null:{id:t,title:n,steps:i(a),notes:i(o)}}function s(e){if(!r(e))return null;let{problem:t,fix:n}=e;return typeof t!=`string`||typeof n!=`string`?null:{problem:t,fix:n}}function c(e){if(!r(e))return null;let{label:t,run:n}=e;return typeof t!=`string`||typeof n!=`function`?null:{label:t,run:e=>{Reflect.apply(n,void 0,[e])}}}function l(n){let l=n.getPluginConfig(t).options,u=r(l)?l:{},d=r(u.guide)?u.guide:{},f=r(u.launcher)?u.launcher:{},p=u.environmentLabel;return{readOnly:u.readOnly===!0,environmentLabel:typeof p==`string`&&p.length>0?p:void 0,hiddenExperienceKeys:new Set([e,...i(u.hiddenExperienceKeys)]),journeyPrecedence:i(u.journeyPrecedence),codeOwnedFields:new Set(i(u.codeOwnedFields)),answerFollowUp:c(u.answerFollowUp),guide:{sections:(Array.isArray(d.sections)?d.sections:[]).map(o).filter(e=>e!==null),fixes:(Array.isArray(d.fixes)?d.fixes:[]).map(s).filter(e=>e!==null)},launcher:{position:a(f.position)?f.position:`bottom-right`,autoHide:typeof f.autoHide!=`boolean`||f.autoHide}}}export{e as DEVTOOLS_EXPERIENCE_KEY,n as LAUNCHER_POSITIONS,l as readDevtoolsOptions};

package/dist/plugins/devtools/plugin.d.ts

@@ -1,9 +1,9 @@
 /** @file Svelte devtools plugin that registers and lazily loads the Picked DevTools experience. */
 import { type Plugin } from '@picked/client';
 import type { CustomTool } from './customTools';
-/** Plugin name under which the devtools plugin stores its config (including registered custom tools). */
-export declare const DEVTOOLS_PLUGIN_NAME = "svelte-devtools";
-export interface SvelteDevtoolsPluginOptions {
+import type { DevtoolsPanelOptions } from './options';
+export { DEVTOOLS_PLUGIN_NAME } from './constants';
+export interface SvelteDevtoolsPluginOptions extends DevtoolsPanelOptions {
     /**
      * When `true`, the devtools experience launches automatically on page load.
      * When `false`, devtools can only be opened via the Picked Chrome extension,
@@ -14,10 +14,10 @@ export interface SvelteDevtoolsPluginOptions {
      */
     enabled?: boolean;
     /**
-     * Project-specific custom dev tools surfaced under the "Custom Tools" tab. Each tool's
-     * `component` is framework-adapted (via `adaptReactComponent` or `adaptSvelteComponent`), so it
-     * can be authored in the host app's framework and still receive the live Picked client the way
-     * an experience component does.
+     * Project-specific custom tools. Each tool's `component` is framework-adapted (via
+     * `adaptReactComponent` or `adaptSvelteComponent`), so it can be authored in the host app's
+     * framework and still receive the live Picked client the way an experience component does. A
+     * tool's `placement` decides whether it is a tab of its own or sits under Developer.
      *
      * @default []
      */
@@ -32,7 +32,7 @@ export interface SvelteDevtoolsPluginOptions {
  * @example
  * ```typescript
  * const client = new Picked({
- *   plugins: [...svelteDevtoolsPlugin({ enabled: true })],
+ *   plugins: [...svelteDevtoolsPlugin({ enabled: true, launcher: { position: 'top-right' } })],
  * })
  * ```
  */

package/dist/plugins/devtools/plugin.js

@@ -1 +1 @@
-import{adaptSvelteComponent as e}from"../../component.js";import{__vitePreload as t}from"../../_virtual/_vite/preload-helper.js";import{lazyComponent as n}from"@picked/client";import{createExperience as r,createExperiencePlugin as i}from"@picked/client/plugins/create-experience";var a=`svelte-devtools`,o=o=>{let s=r({id:`devtools`,key:`devtools`,name:`Picked Devtools`,condition:!1,initializeOpen:!1,targets:[{selector:`body`,placement:`append`}],component:e(n(()=>t(()=>import(`./DevToolsExperience.svelte`),[])))});return s.addStep({name:`Tools`}),[{name:a,setup:e=>{let t=!!e.searchParams[`preview-token`]?.[0];return(o?.enabled||t)&&e.eventBus.watch(t=>{t.type===`ready`&&e.experiences.launch({key:s.key,options:{bypassCondition:!0}})}),{customTools:o?.customTools??[]}}},i({experiences:[s]})]};export{a as DEVTOOLS_PLUGIN_NAME,o as svelteDevtoolsPlugin};
+import{adaptSvelteComponent as e}from"../../component.js";import{DEVTOOLS_EXPERIENCE_KEY as t,DEVTOOLS_PLUGIN_NAME as n}from"./constants.js";import{__vitePreload as r}from"../../_virtual/_vite/preload-helper.js";import{lazyComponent as i}from"@picked/client";import{createExperience as a,createExperiencePlugin as o}from"@picked/client/plugins/create-experience";var s=s=>{let{enabled:c,customTools:l,...u}=s??{},d=a({id:t,key:t,name:`Picked Devtools`,condition:!1,initializeOpen:!1,targets:[{selector:`body`,placement:`append`}],component:e(i(()=>r(()=>import(`./DevToolsExperience.svelte`),[])))});return d.addStep({name:`Tools`}),[{name:n,setup:e=>{let t=!!e.searchParams[`preview-token`]?.[0];return(c||t)&&e.eventBus.watch(t=>{t.type===`ready`&&e.experiences.launch({key:d.key,options:{bypassCondition:!0}})}),{customTools:l??[],options:u}}},o({experiences:[d]})]};export{n as DEVTOOLS_PLUGIN_NAME,s as svelteDevtoolsPlugin};

package/dist/plugins/devtools/posture-context.d.ts

@@ -0,0 +1,15 @@
+import type { SafetyPosture } from './derive';
+/**
+ * Makes the posture available to every screen the devtools shell renders.
+ *
+ * @param {SafetyPosture} posture - What this session may do.
+ * @example setPostureContext(derivePosture({ readOnly: true }))
+ */
+export declare function setPostureContext(posture: SafetyPosture): void;
+/**
+ * Reads the reason writes are withheld, for a screen rendered inside the devtools shell.
+ *
+ * @returns {string | null} Why this session is read-only, or `null` when it may write.
+ * @example const readOnlyReason = readOnlyReasonFromContext()
+ */
+export declare function readOnlyReasonFromContext(): string | null;

package/dist/plugins/devtools/posture-context.js

@@ -0,0 +1 @@
+import{getContext as e,setContext as t}from"svelte";var n=Symbol(`picked-devtools-posture`);function r(e){t(n,e)}function i(){let t=e(n);return typeof t!=`object`||!t||!(`readOnly`in t)||t.readOnly!==!0?null:`reason`in t&&typeof t.reason==`string`?t.reason:`Read-only`}export{i as readOnlyReasonFromContext,r as setPostureContext};