@particle-academy/react-fancy 5.31.0 → 5.33.0

package/dist/index-C8PKWA_5.d.cts

@@ -0,0 +1,153 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * A paste held beside a composer rather than inserted into it.
+ *
+ * There is deliberately **no `length` field.** It would be `text.length` and
+ * nothing else, and a derived value stored beside its source is a value that can
+ * disagree with it — the two drift the moment anything edits one. Read
+ * `paste.text.length`.
+ */
+interface HeldPaste {
+    id: string;
+    text: string;
+}
+/**
+ * The minimum of a clipboard event this hook touches.
+ *
+ * Structural rather than `React.ClipboardEvent` so a host can call it from a
+ * native listener, a synthetic one, or a test double. React's own event satisfies
+ * it.
+ */
+interface PasteEventLike {
+    clipboardData?: {
+        getData(type: string): string;
+    } | null;
+    preventDefault(): void;
+}
+interface UsePastePillsOptions {
+    /**
+     * Hold a paste of at least this many characters. Try 500 — about a long
+     * paragraph.
+     *
+     * **No default, on purpose.** Paste is a fundamental interaction, so holding one
+     * is something a host asks for rather than something it discovers. Omit this and
+     * `handlePaste` always returns `false` and touches nothing.
+     */
+    threshold?: number;
+    /** Own the list yourself. Omit to let the hook keep it. */
+    heldPastes?: HeldPaste[];
+    onHeldPastesChange?: (pastes: HeldPaste[]) => void;
+}
+interface UsePastePillsResult {
+    heldPastes: HeldPaste[];
+    /**
+     * Call this from your OWN paste handler. Returns `true` if it took the paste —
+     * in which case it has already called `preventDefault()` — and `false` if it
+     * declined, having touched nothing.
+     *
+     * Composable on purpose: a host whose handler already intercepts paste for its
+     * own reasons needs to ask "did you want this?" rather than hand over the event.
+     *
+     *     function onPaste(e) {
+     *       if (pills.handlePaste(e)) return;
+     *       // ...your own handling
+     *     }
+     */
+    handlePaste: (event: PasteEventLike) => boolean;
+    /**
+     * Removes the paste and returns its text, for the host to insert into its own
+     * surface. `undefined` if there is no such id.
+     *
+     * The hook cannot insert it — it owns no DOM and does not know what a host's
+     * surface is. That is the point.
+     */
+    expand: (id: string) => string | undefined;
+    /** Discard one without returning it. */
+    remove: (id: string) => void;
+    /** Empty the list, e.g. after a send. */
+    clear: () => void;
+}
+/**
+ * Hold a large paste as state, so a composer can show it as a pill instead of
+ * turning itself into a scrolling wall.
+ *
+ * ---------------------------------------------------------------------------
+ * Why this is a hook and not just a feature of `Composer`
+ * ---------------------------------------------------------------------------
+ *
+ * `Composer` shipped the behaviour in 5.31.0 and the MOIC estate, who specified it,
+ * then established something I had missed: their chat input is a contenteditable
+ * rendering inline `[deal:42|Acme]` badges, so they **cannot** adopt `Composer` (a
+ * plain textarea) however much they want its behaviour. Their plan to delete their
+ * own composer when ours landed could never have worked.
+ *
+ * So the logic lives here and **`Composer` is its first caller.** One
+ * implementation rather than two, which matters more than the convenience: two
+ * copies of a rule drift, and the copy nobody reads is the one that rots. The rule
+ * that must not drift is the one in `Composer`'s own tests — a send with pills
+ * still closed carries the text.
+ *
+ * It owns no DOM. The host renders the pills.
+ *
+ * ---------------------------------------------------------------------------
+ * Who actually calls this (as of 5.32.0): `Composer`, and nothing else
+ * ---------------------------------------------------------------------------
+ *
+ * The estate that specified it **withdrew before adopting it**, hours after it
+ * shipped — their design moved the pill INTO the message as a `[paste:id|label]`
+ * marker in the same grammar as their other object tags, which makes the message
+ * itself the record of what is attached. A parallel `heldPastes` array would then be
+ * a second place answering "what am I sending?", and the two would disagree the
+ * moment someone backspaced a badge. Their reasoning was better than the spec.
+ *
+ * Recorded because a reader should not infer an extension point under active
+ * external use. It is kept rather than withdrawn for two reasons that are about
+ * cost, not optimism: it is published API on a 5.x package, so removing it needs a
+ * major; and `Composer` calls it, so it is exercised by that component's tests on
+ * every run and cannot rot unnoticed.
+ *
+ * **It gets no further surface without a real caller.** No extra options, no second
+ * hook. An API with one hypothetical consumer is how a package accumulates surface
+ * nobody uses.
+ */
+declare function usePastePills({ threshold, heldPastes: controlledHeldPastes, onHeldPastesChange, }?: UsePastePillsOptions): UsePastePillsResult;
+
+interface ComposerProps {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+    placeholder?: string;
+    actions?: ReactNode;
+    disabled?: boolean;
+    className?: string;
+    /**
+     * Hold a paste of at least this many characters beside the composer as a pill,
+     * instead of inserting it. Try 500 — about a long paragraph.
+     *
+     * **Omit it and paste behaves exactly as it always has.** Opt-in on purpose:
+     * paste is a fundamental interaction and this library is past 1.0, so a minor
+     * release must not quietly change what pasting does for every consumer. There is
+     * no default threshold for the same reason.
+     *
+     * Below the threshold nothing changes at all — no prevented event, no pill, no
+     * ceremony for an address or a name.
+     */
+    pasteThreshold?: number;
+    /**
+     * The held pastes, if you want to own them.
+     *
+     * Controllable rather than internal because the component contract forbids
+     * internal-only state for anything an agent might need to read or write — an
+     * agent driving this surface has to be able to see that a paste is attached, and
+     * to attach one itself.
+     */
+    heldPastes?: HeldPaste[];
+    onHeldPastesChange?: (pastes: HeldPaste[]) => void;
+}
+
+declare const Composer: react.ForwardRefExoticComponent<ComposerProps & react.RefAttributes<HTMLDivElement>>;
+
+export { Composer as C, type HeldPaste as H, type PasteEventLike as P, type UsePastePillsOptions as U, type ComposerProps as a, type UsePastePillsResult as b, usePastePills as u };

package/dist/index-C8PKWA_5.d.ts

@@ -0,0 +1,153 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * A paste held beside a composer rather than inserted into it.
+ *
+ * There is deliberately **no `length` field.** It would be `text.length` and
+ * nothing else, and a derived value stored beside its source is a value that can
+ * disagree with it — the two drift the moment anything edits one. Read
+ * `paste.text.length`.
+ */
+interface HeldPaste {
+    id: string;
+    text: string;
+}
+/**
+ * The minimum of a clipboard event this hook touches.
+ *
+ * Structural rather than `React.ClipboardEvent` so a host can call it from a
+ * native listener, a synthetic one, or a test double. React's own event satisfies
+ * it.
+ */
+interface PasteEventLike {
+    clipboardData?: {
+        getData(type: string): string;
+    } | null;
+    preventDefault(): void;
+}
+interface UsePastePillsOptions {
+    /**
+     * Hold a paste of at least this many characters. Try 500 — about a long
+     * paragraph.
+     *
+     * **No default, on purpose.** Paste is a fundamental interaction, so holding one
+     * is something a host asks for rather than something it discovers. Omit this and
+     * `handlePaste` always returns `false` and touches nothing.
+     */
+    threshold?: number;
+    /** Own the list yourself. Omit to let the hook keep it. */
+    heldPastes?: HeldPaste[];
+    onHeldPastesChange?: (pastes: HeldPaste[]) => void;
+}
+interface UsePastePillsResult {
+    heldPastes: HeldPaste[];
+    /**
+     * Call this from your OWN paste handler. Returns `true` if it took the paste —
+     * in which case it has already called `preventDefault()` — and `false` if it
+     * declined, having touched nothing.
+     *
+     * Composable on purpose: a host whose handler already intercepts paste for its
+     * own reasons needs to ask "did you want this?" rather than hand over the event.
+     *
+     *     function onPaste(e) {
+     *       if (pills.handlePaste(e)) return;
+     *       // ...your own handling
+     *     }
+     */
+    handlePaste: (event: PasteEventLike) => boolean;
+    /**
+     * Removes the paste and returns its text, for the host to insert into its own
+     * surface. `undefined` if there is no such id.
+     *
+     * The hook cannot insert it — it owns no DOM and does not know what a host's
+     * surface is. That is the point.
+     */
+    expand: (id: string) => string | undefined;
+    /** Discard one without returning it. */
+    remove: (id: string) => void;
+    /** Empty the list, e.g. after a send. */
+    clear: () => void;
+}
+/**
+ * Hold a large paste as state, so a composer can show it as a pill instead of
+ * turning itself into a scrolling wall.
+ *
+ * ---------------------------------------------------------------------------
+ * Why this is a hook and not just a feature of `Composer`
+ * ---------------------------------------------------------------------------
+ *
+ * `Composer` shipped the behaviour in 5.31.0 and the MOIC estate, who specified it,
+ * then established something I had missed: their chat input is a contenteditable
+ * rendering inline `[deal:42|Acme]` badges, so they **cannot** adopt `Composer` (a
+ * plain textarea) however much they want its behaviour. Their plan to delete their
+ * own composer when ours landed could never have worked.
+ *
+ * So the logic lives here and **`Composer` is its first caller.** One
+ * implementation rather than two, which matters more than the convenience: two
+ * copies of a rule drift, and the copy nobody reads is the one that rots. The rule
+ * that must not drift is the one in `Composer`'s own tests — a send with pills
+ * still closed carries the text.
+ *
+ * It owns no DOM. The host renders the pills.
+ *
+ * ---------------------------------------------------------------------------
+ * Who actually calls this (as of 5.32.0): `Composer`, and nothing else
+ * ---------------------------------------------------------------------------
+ *
+ * The estate that specified it **withdrew before adopting it**, hours after it
+ * shipped — their design moved the pill INTO the message as a `[paste:id|label]`
+ * marker in the same grammar as their other object tags, which makes the message
+ * itself the record of what is attached. A parallel `heldPastes` array would then be
+ * a second place answering "what am I sending?", and the two would disagree the
+ * moment someone backspaced a badge. Their reasoning was better than the spec.
+ *
+ * Recorded because a reader should not infer an extension point under active
+ * external use. It is kept rather than withdrawn for two reasons that are about
+ * cost, not optimism: it is published API on a 5.x package, so removing it needs a
+ * major; and `Composer` calls it, so it is exercised by that component's tests on
+ * every run and cannot rot unnoticed.
+ *
+ * **It gets no further surface without a real caller.** No extra options, no second
+ * hook. An API with one hypothetical consumer is how a package accumulates surface
+ * nobody uses.
+ */
+declare function usePastePills({ threshold, heldPastes: controlledHeldPastes, onHeldPastesChange, }?: UsePastePillsOptions): UsePastePillsResult;
+
+interface ComposerProps {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+    placeholder?: string;
+    actions?: ReactNode;
+    disabled?: boolean;
+    className?: string;
+    /**
+     * Hold a paste of at least this many characters beside the composer as a pill,
+     * instead of inserting it. Try 500 — about a long paragraph.
+     *
+     * **Omit it and paste behaves exactly as it always has.** Opt-in on purpose:
+     * paste is a fundamental interaction and this library is past 1.0, so a minor
+     * release must not quietly change what pasting does for every consumer. There is
+     * no default threshold for the same reason.
+     *
+     * Below the threshold nothing changes at all — no prevented event, no pill, no
+     * ceremony for an address or a name.
+     */
+    pasteThreshold?: number;
+    /**
+     * The held pastes, if you want to own them.
+     *
+     * Controllable rather than internal because the component contract forbids
+     * internal-only state for anything an agent might need to read or write — an
+     * agent driving this surface has to be able to see that a paste is attached, and
+     * to attach one itself.
+     */
+    heldPastes?: HeldPaste[];
+    onHeldPastesChange?: (pastes: HeldPaste[]) => void;
+}
+
+declare const Composer: react.ForwardRefExoticComponent<ComposerProps & react.RefAttributes<HTMLDivElement>>;
+
+export { Composer as C, type HeldPaste as H, type PasteEventLike as P, type UsePastePillsOptions as U, type ComposerProps as a, type UsePastePillsResult as b, usePastePills as u };