@aglyn/plugins-email 1.0.0-beta.143

package/src/lib/components/campaign-topic-select.js

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { activeEmailTopics, DEFAULT_CAMPAIGN_TOPIC_ID } from "@aglyn/aglyn";
+import { MenuItem, TextField } from "@mui/material";
+import { useEffect } from "react";
+import { useOrgEmailTopics } from "./use-org-email-topics.js";
+/**
+ * WHICH STREAM this campaign belongs to, chosen before it is sent.
+ *
+ * The topic decides three things at once: which recipients the send skips
+ * (anyone who has left this stream), what the preference page linked from the
+ * footer highlights as "this email", and which stream a resulting unsubscribe
+ * is recorded against. So it is a composer field rather than a setting — it is
+ * a property of the message, and the same site sends promotions and a
+ * newsletter in the same week.
+ *
+ * ## Why this is its own component
+ *
+ * The composer (`campaign-composer.tsx`) is a large component under concurrent
+ * edit. Keeping the picker separate means it can be dropped into the
+ * composer's field stack as one line and carries its own read of the org
+ * catalog, rather than threading a fifth collection listener through a
+ * component that already holds four.
+ *
+ * Retired topics are not offered. A campaign may not be composed under a
+ * stream nobody can unsubscribe from — but a campaign already SENT under one
+ * keeps resolving, which is why retiring is not deleting. See
+ * `email-topics-card.tsx`.
+ */ export function CampaignTopicSelect(props) {
+    const { hostId, value, onChange, disabled } = props;
+    const { topics } = useOrgEmailTopics(hostId);
+    const options = activeEmailTopics(topics);
+    /*
+   * SETTLE ON A REAL OPTION, rather than submitting an empty topic.
+   *
+   * The send resolves an absent topic to the default anyway, so an empty value
+   * would still produce a correct send — but it would produce one whose topic
+   * the composer never showed the author. A merchant is entitled to see which
+   * stream they are about to mail before they press send, and a select that
+   * reads blank while the server has already decided is the shape of a field
+   * that lies.
+   *
+   * It also re-settles when the chosen topic leaves the list, which is what a
+   * topic retired in another tab looks like from here.
+   */ useEffect(()=>{
+        var _options_find;
+        if (!options.length) return;
+        if (options.some((topic)=>topic.id === value)) return;
+        const fallback = (_options_find = options.find((topic)=>topic.id === DEFAULT_CAMPAIGN_TOPIC_ID)) != null ? _options_find : options[0];
+        onChange(fallback.id);
+    }, [
+        options,
+        value,
+        onChange
+    ]);
+    return /*#__PURE__*/ _jsx(TextField, {
+        select: true,
+        size: "small",
+        label: "Topic",
+        value: options.some((topic)=>topic.id === value) ? value : '',
+        onChange: (event)=>onChange(event.target.value),
+        disabled: disabled || !options.length,
+        helperText: 'Recipients who have left this stream are skipped, and the ' + 'unsubscribe link in this email offers to stop it on its own.',
+        children: options.map((topic)=>/*#__PURE__*/ _jsx(MenuItem, {
+                value: topic.id,
+                children: topic.name
+            }, topic.id))
+    });
+}
+export default CampaignTopicSelect;
+
+//# sourceMappingURL=campaign-topic-select.js.map

package/src/lib/components/campaign-topic-select.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/email/src/lib/components/campaign-topic-select.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n'use client'\n\nimport { activeEmailTopics, DEFAULT_CAMPAIGN_TOPIC_ID } from '@aglyn/aglyn'\nimport { MenuItem, TextField } from '@mui/material'\nimport { useEffect } from 'react'\nimport { useOrgEmailTopics } from './use-org-email-topics'\n\nexport interface CampaignTopicSelectProps {\n  hostId: string\n  /** The chosen topic id; empty until the effect below settles it. */\n  value: string\n  onChange: (topicId: string) => void\n  disabled?: boolean\n}\n\n/**\n * WHICH STREAM this campaign belongs to, chosen before it is sent.\n *\n * The topic decides three things at once: which recipients the send skips\n * (anyone who has left this stream), what the preference page linked from the\n * footer highlights as \"this email\", and which stream a resulting unsubscribe\n * is recorded against. So it is a composer field rather than a setting — it is\n * a property of the message, and the same site sends promotions and a\n * newsletter in the same week.\n *\n * ## Why this is its own component\n *\n * The composer (`campaign-composer.tsx`) is a large component under concurrent\n * edit. Keeping the picker separate means it can be dropped into the\n * composer's field stack as one line and carries its own read of the org\n * catalog, rather than threading a fifth collection listener through a\n * component that already holds four.\n *\n * Retired topics are not offered. A campaign may not be composed under a\n * stream nobody can unsubscribe from — but a campaign already SENT under one\n * keeps resolving, which is why retiring is not deleting. See\n * `email-topics-card.tsx`.\n */\nexport function CampaignTopicSelect(props: CampaignTopicSelectProps) {\n  const { hostId, value, onChange, disabled } = props\n  const { topics } = useOrgEmailTopics(hostId)\n  const options = activeEmailTopics(topics)\n\n  /*\n   * SETTLE ON A REAL OPTION, rather than submitting an empty topic.\n   *\n   * The send resolves an absent topic to the default anyway, so an empty value\n   * would still produce a correct send — but it would produce one whose topic\n   * the composer never showed the author. A merchant is entitled to see which\n   * stream they are about to mail before they press send, and a select that\n   * reads blank while the server has already decided is the shape of a field\n   * that lies.\n   *\n   * It also re-settles when the chosen topic leaves the list, which is what a\n   * topic retired in another tab looks like from here.\n   */\n  useEffect(() => {\n    if (!options.length) return\n    if (options.some((topic) => topic.id === value)) return\n    const fallback =\n      options.find((topic) => topic.id === DEFAULT_CAMPAIGN_TOPIC_ID) ??\n      options[0]\n    onChange(fallback.id)\n  }, [options, value, onChange])\n\n  return (\n    <TextField\n      select\n      size=\"small\"\n      label=\"Topic\"\n      value={options.some((topic) => topic.id === value) ? value : ''}\n      onChange={(event) => onChange(event.target.value)}\n      disabled={disabled || !options.length}\n      helperText={\n        'Recipients who have left this stream are skipped, and the ' +\n        'unsubscribe link in this email offers to stop it on its own.'\n      }\n    >\n      {options.map((topic) => (\n        <MenuItem key={topic.id} value={topic.id}>\n          {topic.name}\n        </MenuItem>\n      ))}\n    </TextField>\n  )\n}\n\nexport default CampaignTopicSelect\n"],"names":["activeEmailTopics","DEFAULT_CAMPAIGN_TOPIC_ID","MenuItem","TextField","useEffect","useOrgEmailTopics","CampaignTopicSelect","props","hostId","value","onChange","disabled","topics","options","length","some","topic","id","fallback","find","select","size","label","event","target","helperText","map","name"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;;AAEA,SAASA,iBAAiB,EAAEC,yBAAyB,QAAQ,eAAc;AAC3E,SAASC,QAAQ,EAAEC,SAAS,QAAQ,gBAAe;AACnD,SAASC,SAAS,QAAQ,QAAO;AACjC,SAASC,iBAAiB,QAAQ,4BAAwB;AAU1D;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,SAASC,oBAAoBC,KAA+B;IACjE,MAAM,EAAEC,MAAM,EAAEC,KAAK,EAAEC,QAAQ,EAAEC,QAAQ,EAAE,GAAGJ;IAC9C,MAAM,EAAEK,MAAM,EAAE,GAAGP,kBAAkBG;IACrC,MAAMK,UAAUb,kBAAkBY;IAElC;;;;;;;;;;;;GAYC,GACDR,UAAU;YAINS;QAHF,IAAI,CAACA,QAAQC,MAAM,EAAE;QACrB,IAAID,QAAQE,IAAI,CAAC,CAACC,QAAUA,MAAMC,EAAE,KAAKR,QAAQ;QACjD,MAAMS,YACJL,gBAAAA,QAAQM,IAAI,CAAC,CAACH,QAAUA,MAAMC,EAAE,KAAKhB,sCAArCY,gBACAA,OAAO,CAAC,EAAE;QACZH,SAASQ,SAASD,EAAE;IACtB,GAAG;QAACJ;QAASJ;QAAOC;KAAS;IAE7B,qBACE,KAACP;QACCiB,MAAM;QACNC,MAAK;QACLC,OAAM;QACNb,OAAOI,QAAQE,IAAI,CAAC,CAACC,QAAUA,MAAMC,EAAE,KAAKR,SAASA,QAAQ;QAC7DC,UAAU,CAACa,QAAUb,SAASa,MAAMC,MAAM,CAACf,KAAK;QAChDE,UAAUA,YAAY,CAACE,QAAQC,MAAM;QACrCW,YACE,+DACA;kBAGDZ,QAAQa,GAAG,CAAC,CAACV,sBACZ,KAACd;gBAAwBO,OAAOO,MAAMC,EAAE;0BACrCD,MAAMW,IAAI;eADEX,MAAMC,EAAE;;AAM/B;AAEA,eAAeX,oBAAmB"}

package/src/lib/components/dynamic-list-rule-fields.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Every field of `DynamicListRule`, with a control for each.
+ *
+ * ## Why the whole rule, and why in one place
+ *
+ * Every dimension the matcher reads has a control here, including the two
+ * that are answered by a keyed lookup rather than by the person's own record
+ * — engagement, and membership of another audience — and the combinator that
+ * decides whether the filters are ANDed, ORed or inverted. Needing to
+ * hand-write a stored structure to reach a shipped engine is a missing
+ * picker, not a power-user affordance, which is the standard this form is
+ * held to rather than a count of fields.
+ *
+ * One component rather than a form on the create card and a second on the edit
+ * page: the two would drift, and the half that drifts is whichever the
+ * merchant is not looking at. A rule authored at creation and the same rule
+ * reopened for editing are the same questions.
+ *
+ * ## The draft is text, the value is a rule
+ *
+ * The controls hold what was TYPED — `vip, ` is a legitimate intermediate
+ * state of a tag list, and a component that round-tripped every keystroke
+ * through `normalizeDynamicListRule` would delete the comma the moment it was
+ * typed. So the draft is strings, `draftToRule` is the one place it becomes a
+ * rule, and the parent never sees anything else.
+ *
+ * ## Money is entered the way a merchant says it
+ *
+ * `ltvCentsAtLeast` is stored in cents. A field labeled for the stored unit
+ * turns "customers who spent over 500" into customers who spent over five
+ * dollars, silently, and the audience looks plausible either way. The control
+ * takes whole currency units and this file owns the only multiplication.
+ *
+ * ## It reads the segments, and only when it is on screen
+ *
+ * The segment picker needs the org's saved segments, through
+ * `useOrgContactSegments`. That listen belongs to this component so it opens
+ * when a rule is actually being authored — the audiences section's cost is a
+ * list of lists, and a segment read on arrival would be a read for a form
+ * nobody has opened.
+ */
+import { type ContactLifecycleStage, type ContactSource, type DynamicListCustomClause, type DynamicListRule, type DynamicListSource } from '@aglyn/aglyn';
+/**
+ * The rule, in sentences a merchant can read back to themselves.
+ *
+ * Every clause names a dimension that is actually SET, so a rule with four
+ * dimensions reads as four clauses and a rule with one reads as one — an
+ * explanation that also lists the fields a rule does not use is an explanation
+ * the reader has to subtract from. Rendered live beside the controls, because
+ * the question a filter form has to answer continuously is "who does this
+ * describe", and a form of eleven boxes does not answer it on its own.
+ */
+/** Names for the ids a rule stores, so a clause can say "Customers", not a uid. */
+export interface DynamicListRuleNames {
+    /** List id → its name. */
+    lists?: Record<string, string>;
+    /** Segment id → its name. */
+    segments?: Record<string, string>;
+    /** Saved Contacts view id → its name. */
+    views?: Record<string, string>;
+    /** Campaign id → its name. */
+    campaigns?: Record<string, string>;
+    /** Team member uid → how they read on the roster. */
+    members?: Record<string, string>;
+    /** Company id → its name. */
+    companies?: Record<string, string>;
+    /** Custom field key → the definition's label. */
+    fields?: Record<string, string>;
+}
+export declare function describeDynamicListRule(rule: DynamicListRule, names?: DynamicListRuleNames): string[];
+/**
+ * How the filters below combine.
+ *
+ * The three shapes this form authors, mapped onto the rule's two operators:
+ * `all` is the plain AND block, `none` is that block with `negate`, and `any`
+ * puts each filter into its own OR branch. A saved segment is outside all
+ * three — it is resolved once from `segmentId` and always applies, which the
+ * control says on screen rather than leaving to be discovered.
+ */
+export type DynamicListRuleMatch = 'all' | 'any' | 'none';
+/** The rule as the controls hold it: what was typed, not what it means. */
+export interface DynamicListRuleDraft {
+    sources: DynamicListSource[];
+    match: DynamicListRuleMatch;
+    segmentId: string;
+    /** A saved Contacts view's id, resolved by the sweep beside the segment (AGL-2617). */
+    viewId: string;
+    tags: string;
+    captureSources: ContactSource[];
+    formNames: string;
+    /** Campaign ids, from the site's own campaigns picker. */
+    campaignIds: string[];
+    /** `yyyy-mm-dd`, read as UTC — the same instant `Date.parse` gives it. */
+    createdAfter: string;
+    createdBefore: string;
+    ordersCountAtLeast: string;
+    /** WHOLE currency units. `draftToRule` is the only place this becomes cents. */
+    ltvAtLeast: string;
+    lastPurchaseWithinDays: string;
+    noPurchaseForDays: string;
+    openedWithinDays: string;
+    clickedWithinDays: string;
+    notOpenedForDays: string;
+    notClickedForDays: string;
+    inListIds: string[];
+    notInListIds: string[];
+    ownerUids: string[];
+    lifecycleStages: ContactLifecycleStage[];
+    companyIds: string[];
+    custom: DynamicListCustomClause[];
+    /**
+     * The re-engagement window (AGL-2616), typed like the purchase windows
+     * — days, as text, so an empty box is not a zero-day window.
+     */
+    engagedWithinDays: string;
+}
+export declare const EMPTY_RULE_DRAFT: DynamicListRuleDraft;
+/** Comma-separated free text → the trimmed, non-empty values. */
+export declare const splitRuleList: (value: string) => string[];
+/**
+ * A stored rule, as the controls should show it.
+ *
+ * ⚠️ The three shapes {@link DynamicListRuleMatch} names are the shapes this
+ * form AUTHORS. A rule written through the REST API can hold branches the
+ * controls have no place for — a branch with its own `negate`, or top-level
+ * filters alongside branches — and this reads such a rule back as the union
+ * of every filter in it, in `any` mode. It is not a silent rewrite: the
+ * sentences above the controls are computed from `draftToRule(draft)`, so
+ * what a save would store is on screen before the reader saves it.
+ */
+export declare function ruleToDraft(rule: DynamicListRule): DynamicListRuleDraft;
+/** What the controls mean, coerced by the function the matcher reads through. */
+export declare function draftToRule(draft: DynamicListRuleDraft): DynamicListRule;
+export interface DynamicListRuleFieldsProps {
+    /** `['orgs', orgId]` — the resolved org scope the caller already holds. */
+    scope: readonly [string, string];
+    /**
+     * The site whose campaigns the campaign picker offers.
+     *
+     * A list is org-owned and its rule is materialized against ONE site's silos,
+     * which is the same site whose campaigns a form or a screen can be filed
+     * under. Offering the org's every campaign would offer ids the sweep can
+     * never match, because the membership it reads was written by that site.
+     */
+    hostId: string;
+    draft: DynamicListRuleDraft;
+    onChange: (draft: DynamicListRuleDraft) => void;
+    /**
+     * The audience being edited, when there is one.
+     *
+     * Kept out of its own list pickers. A rule that referred to the list it
+     * fills would oscillate — see `dynamicListRuleWithoutListReference`, which
+     * strips it at the sweep as well, because a rule outlives any one form.
+     * Offering it here and stripping it there would show a merchant a filter
+     * that quietly does nothing.
+     */
+    listId?: string;
+}
+export declare function DynamicListRuleFields(props: DynamicListRuleFieldsProps): import("react").JSX.Element;
+export declare namespace DynamicListRuleFields {
+    var displayName: string;
+}
+/**
+ * A draft seeded from a rule that arrives after the form does.
+ *
+ * The edit page mounts before its list document lands, so the controls are
+ * built from an empty rule and filled in once. Seeding ONCE per subject is the
+ * whole point: the document is a live listen, and re-seeding on every snapshot
+ * would overwrite whatever the reader had typed each time anything on the list
+ * changed — including the snapshot the reader's own save produces.
+ */
+export declare function useRuleDraft(rule: DynamicListRule | undefined, resetKey: string): [DynamicListRuleDraft, (draft: DynamicListRuleDraft) => void];
+export default DynamicListRuleFields;