@supersoniks/concorde 4.5.2 → 4.7.0

package/src/docs/example/docs-submit-demos.ts

@@ -0,0 +1,455 @@
+import { html, LitElement, nothing } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import { subscribe } from "@supersoniks/concorde/core/decorators/Subscriber";
+import { Endpoint } from "@supersoniks/concorde/core/utils/endpoint";
+import {
+  DOCS_MOCK_API_BASE,
+  DOCS_MOCK_REQRES_SERVICE,
+} from "../mock-api/urls";
+import {
+  submitClearFormKey,
+  submitEndpointFormKey,
+  submitEndpointResultKey,
+  submitEventFormKey,
+  submitExampleFormKey,
+  submitExampleResultKey,
+  submitFormDataFormKey,
+  submitFormDataResultKey,
+  submitGetFormKey,
+  submitGetResultKey,
+  submitNativeFormKey,
+  submitNestedFormKey,
+  submitNestedResultKey,
+} from "./docs-provider-keys";
+import { tailwind } from "../tailwind";
+
+import "../../core/components/functional/sonic-scope/sonic-scope";
+import "../../core/components/functional/submit/submit";
+import "../../core/components/ui/button/button";
+import "../../core/components/ui/divider/divider";
+import "../../core/components/ui/form/input/input";
+
+type RegisterResult = {
+  id?: number;
+  token?: string;
+  email?: string;
+  error?: string;
+  messages?: { content?: string; status?: string }[];
+  method?: string;
+  query?: { email?: string; password?: string };
+  note?: string;
+};
+
+const registerEndpoint = new Endpoint<RegisterResult>("api/register");
+const registerNestedEndpoint = new Endpoint<RegisterResult>(
+  "api/register/nested",
+);
+const registerEchoEndpoint = new Endpoint<RegisterResult>("api/register/echo");
+const usersListEndpoint = new Endpoint<unknown>("api/users");
+
+function resultLines(r: RegisterResult | null) {
+  if (!r) return nothing;
+  const messageText = r.messages
+    ?.map((m) => m.content)
+    .filter(Boolean)
+    .join(" — ");
+  return html`
+    ${r.id != null
+      ? html`<div>Id : <span class="font-mono">${r.id}</span></div>`
+      : nothing}
+    ${r.email
+      ? html`<div>Email : <span class="font-mono">${r.email}</span></div>`
+      : nothing}
+    ${r.token
+      ? html`<div>Token : <span class="font-mono break-all">${r.token}</span></div>`
+      : nothing}
+    ${r.method
+      ? html`<div>Method : <span class="font-mono">${r.method}</span></div>`
+      : nothing}
+    ${r.query
+      ? html`<div>
+          Query :
+          <span class="font-mono"
+            >email=${r.query.email ?? ""}, password=${r.query.password ?? ""}</span
+          >
+        </div>`
+      : nothing}
+    ${r.note ? html`<p class="text-neutral-500">${r.note}</p>` : nothing}
+    ${r.error ? html`<div class="text-red-600">${r.error}</div>` : nothing}
+    ${messageText ? html`<div class="text-red-600">${messageText}</div>` : nothing}
+  `;
+}
+
+/**
+ * Form + result — `submitResultDataProvider` is filled after POST to mock `/api/register`.
+ */
+@customElement("docs-submit-demo")
+export class DocsSubmitDemo extends LitElement {
+  static styles = [tailwind];
+
+  @subscribe(submitExampleResultKey)
+  @state()
+  private result: RegisterResult | null = null;
+
+  private resultBlock() {
+    const r = this.result;
+    if (!r || (!r.id && !r.token && !r.error && !r.messages?.length)) {
+      return html`
+        <p class="mt-4 text-sm text-neutral-500">
+          Submit the form to see <code>id</code> and <code>token</code> here.
+        </p>
+      `;
+    }
+    return html`
+      <sonic-divider align="left" class="mt-6">Result</sonic-divider>
+      <div class="mt-2 space-y-1 text-sm">${resultLines(r)}</div>
+    `;
+  }
+
+  render() {
+    return html`
+      <sonic-scope
+        serviceURL=${DOCS_MOCK_REQRES_SERVICE}
+        dataProvider=${registerEndpoint.path}
+        formDataProvider=${submitExampleFormKey.path}
+        submitResultDataProvider=${submitExampleResultKey.path}
+        class="max-w-lg block"
+      >
+        <sonic-submit onEnterKey>
+          <div class="mb-4 grid grid-cols-2 gap-4">
+            <sonic-input
+              required
+              name="email"
+              type="email"
+              value="eve.holt@reqres.in"
+            ></sonic-input>
+            <sonic-input
+              required
+              type="password"
+              name="password"
+              value="pistol"
+            ></sonic-input>
+          </div>
+        </sonic-submit>
+        <sonic-submit onClick>
+          <sonic-button type="success" class="w-full">Submit</sonic-button>
+        </sonic-submit>
+      </sonic-scope>
+      ${this.resultBlock()}
+    `;
+  }
+}
+
+/** `clearedDataOnSuccess` resets listed publishers when the API returns a result object. */
+@customElement("docs-submit-clear-demo")
+export class DocsSubmitClearDemo extends LitElement {
+  static styles = [tailwind];
+
+  render() {
+    return html`
+      <sonic-scope
+        serviceURL=${DOCS_MOCK_REQRES_SERVICE}
+        dataProvider=${registerEndpoint.path}
+        formDataProvider=${submitClearFormKey.path}
+        clearedDataOnSuccess=${submitClearFormKey.path}
+        class="max-w-lg block"
+      >
+        <sonic-submit onClick>
+          <div class="mb-4 grid grid-cols-2 gap-4">
+            <sonic-input
+              required
+              name="email"
+              type="email"
+              value="eve.holt@reqres.in"
+            ></sonic-input>
+            <sonic-input
+              required
+              type="password"
+              name="password"
+              value="pistol"
+            ></sonic-input>
+          </div>
+          <sonic-button type="success" class="w-full">Submit and clear form</sonic-button>
+        </sonic-submit>
+      </sonic-scope>
+      <p class="mt-3 text-sm text-neutral-500">
+        After submit, <code>clearedDataOnSuccess="submit-clear-form"</code> resets
+        the publisher (inputs should empty).
+      </p>
+    `;
+  }
+}
+
+/** `submit-result-key` keeps only a nested part of the JSON before writing the result publisher. */
+@customElement("docs-submit-result-key-demo")
+export class DocsSubmitResultKeyDemo extends LitElement {
+  static styles = [tailwind];
+
+  @subscribe(submitNestedResultKey)
+  @state()
+  private result: RegisterResult | null = null;
+
+  render() {
+    const r = this.result;
+    return html`
+      <sonic-scope
+        serviceURL=${DOCS_MOCK_REQRES_SERVICE}
+        dataProvider=${registerNestedEndpoint.path}
+        formDataProvider=${submitNestedFormKey.path}
+        submitResultDataProvider=${submitNestedResultKey.path}
+        class="max-w-lg block"
+      >
+        <sonic-submit onClick submit-result-key="data">
+          <div class="mb-4 grid grid-cols-2 gap-4">
+            <sonic-input
+              required
+              name="email"
+              type="email"
+              value="eve.holt@reqres.in"
+            ></sonic-input>
+            <sonic-input
+              required
+              type="password"
+              name="password"
+              value="pistol"
+            ></sonic-input>
+          </div>
+          <sonic-button type="primary" class="w-full">Submit (nested JSON)</sonic-button>
+        </sonic-submit>
+      </sonic-scope>
+      <sonic-divider align="left" class="mt-4">Stored in publisher</sonic-divider>
+      <div class="mt-2 text-sm">
+        ${r?.id != null
+          ? html`<div>id from <code>data</code> : ${r.id}</div>`
+          : html`<p class="text-neutral-500">Submit to extract <code>data.id</code> / <code>data.token</code>.</p>`}
+      </div>
+    `;
+  }
+}
+
+/** `sendAsFormData` sends multipart <code>FormData</code> instead of JSON. */
+@customElement("docs-submit-formdata-demo")
+export class DocsSubmitFormDataDemo extends LitElement {
+  static styles = [tailwind];
+
+  @subscribe(submitFormDataResultKey)
+  @state()
+  private result: RegisterResult | null = null;
+
+  render() {
+    return html`
+      <sonic-scope
+        serviceURL=${DOCS_MOCK_REQRES_SERVICE}
+        dataProvider=${registerEndpoint.path}
+        formDataProvider=${submitFormDataFormKey.path}
+        submitResultDataProvider=${submitFormDataResultKey.path}
+        class="max-w-lg block"
+      >
+        <sonic-submit onClick sendAsFormData>
+          <div class="mb-4 grid grid-cols-2 gap-4">
+            <sonic-input
+              required
+              name="email"
+              type="email"
+              value="eve.holt@reqres.in"
+            ></sonic-input>
+            <sonic-input
+              required
+              type="password"
+              name="password"
+              value="pistol"
+            ></sonic-input>
+          </div>
+          <sonic-button type="primary" class="w-full">Submit as FormData</sonic-button>
+        </sonic-submit>
+      </sonic-scope>
+      <div class="mt-3 text-sm">
+        ${this.result?.token
+          ? html`Token received: <span class="font-mono">${this.result.token}</span>`
+          : html`<p class="text-neutral-500">Mock accepts JSON and multipart for <code>/api/register</code>.</p>`}
+      </div>
+    `;
+  }
+}
+
+/** `method="get"` appends publisher fields as query string (mock echoes them). */
+@customElement("docs-submit-get-demo")
+export class DocsSubmitGetDemo extends LitElement {
+  static styles = [tailwind];
+
+  @subscribe(submitGetResultKey)
+  @state()
+  private result: RegisterResult | null = null;
+
+  render() {
+    return html`
+      <sonic-scope
+        serviceURL=${DOCS_MOCK_REQRES_SERVICE}
+        dataProvider=${registerEchoEndpoint.path}
+        formDataProvider=${submitGetFormKey.path}
+        submitResultDataProvider=${submitGetResultKey.path}
+        class="max-w-lg block"
+      >
+        <sonic-submit onClick method="get">
+          <div class="mb-4 grid grid-cols-2 gap-4">
+            <sonic-input name="email" type="email" value="demo@example.com"></sonic-input>
+            <sonic-input name="password" type="password" value="secret"></sonic-input>
+          </div>
+          <sonic-button type="neutral" class="w-full">GET with query string</sonic-button>
+        </sonic-submit>
+      </sonic-scope>
+      <div class="mt-3 space-y-1 text-sm">${resultLines(this.result)}</div>
+    `;
+  }
+}
+
+/** `native` — sync publisher to a real <form> and trigger browser submit (iframe target). */
+@customElement("docs-submit-native-demo")
+export class DocsSubmitNativeDemo extends LitElement {
+  static styles = [tailwind];
+
+  private formAction = `${DOCS_MOCK_API_BASE}/api/register`;
+
+  render() {
+    return html`
+      <form
+        action=${this.formAction}
+        method="post"
+        target="docs-submit-native-frame"
+        class="max-w-lg"
+      >
+        <sonic-scope formDataProvider=${submitNativeFormKey.path}>
+          <sonic-submit native onClick>
+            <div class="mb-4 grid grid-cols-2 gap-4">
+              <sonic-input
+                required
+                name="email"
+                type="email"
+                value="eve.holt@reqres.in"
+              ></sonic-input>
+              <sonic-input
+                required
+                type="password"
+                name="password"
+                value="pistol"
+              ></sonic-input>
+            </div>
+            <sonic-button type="success" class="w-full"
+              >Native form POST</sonic-button
+            >
+          </sonic-submit>
+        </sonic-scope>
+      </form>
+      <p class="mt-2 text-sm text-neutral-500">
+        Response loads in the iframe below (full page navigation is avoided via
+        <code>target</code>).
+      </p>
+      <iframe
+        name="docs-submit-native-frame"
+        title="Native form response"
+        class="mt-2 h-24 w-full rounded border border-neutral-200 bg-neutral-50 text-xs"
+      ></iframe>
+    `;
+  }
+}
+
+/** Bubbles <code>submit</code> custom event with API result in <code>detail</code>. */
+@customElement("docs-submit-event-demo")
+export class DocsSubmitEventDemo extends LitElement {
+  static styles = [tailwind];
+
+  @state()
+  private lastEvent: string | null = null;
+
+  private onSubmit = (e: CustomEvent<RegisterResult>) => {
+    const d = e.detail;
+    this.lastEvent = d?.token
+      ? `token=${d.token}`
+      : d?.messages?.[0]?.content ?? JSON.stringify(d);
+  };
+
+  render() {
+    return html`
+      <sonic-scope
+        serviceURL=${DOCS_MOCK_REQRES_SERVICE}
+        dataProvider="api/register"
+        formDataProvider="submit-event-form"
+        class="max-w-lg block"
+      >
+        <sonic-submit onClick @submit=${this.onSubmit}>
+          <div class="mb-4 grid grid-cols-2 gap-4">
+            <sonic-input
+              required
+              name="email"
+              type="email"
+              value="eve.holt@reqres.in"
+            ></sonic-input>
+            <sonic-input
+              required
+              type="password"
+              name="password"
+              value="pistol"
+            ></sonic-input>
+          </div>
+          <sonic-button type="primary" class="w-full">Submit (listen event)</sonic-button>
+        </sonic-submit>
+      </sonic-scope>
+      <p class="mt-3 text-sm">
+        ${this.lastEvent
+          ? html`Last <code>submit</code> event: <span class="font-mono">${this.lastEvent}</span>`
+          : html`<span class="text-neutral-500">Click submit — handler reads <code>event.detail</code>.</span>`}
+      </p>
+    `;
+  }
+}
+
+/** <code>endPoint</code> overrides <code>dataProvider</code> for the request path. */
+@customElement("docs-submit-endpoint-demo")
+export class DocsSubmitEndpointDemo extends LitElement {
+  static styles = [tailwind];
+
+  @subscribe(submitEndpointResultKey)
+  @state()
+  private result: RegisterResult | null = null;
+
+  render() {
+    return html`
+      <sonic-scope
+        serviceURL=${DOCS_MOCK_REQRES_SERVICE}
+        dataProvider=${usersListEndpoint.path}
+        formDataProvider=${submitEndpointFormKey.path}
+        submitResultDataProvider=${submitEndpointResultKey.path}
+        class="max-w-lg block"
+      >
+        <sonic-submit onClick endPoint=${registerEndpoint.path}>
+          <div class="mb-4 grid grid-cols-2 gap-4">
+            <sonic-input
+              required
+              name="email"
+              type="email"
+              value="eve.holt@reqres.in"
+            ></sonic-input>
+            <sonic-input
+              required
+              type="password"
+              name="password"
+              value="pistol"
+            ></sonic-input>
+          </div>
+          <sonic-button type="primary" class="w-full"
+            >POST via <code>endPoint</code></sonic-button
+          >
+        </sonic-submit>
+      </sonic-scope>
+      <div class="mt-3 text-sm">
+        ${this.result?.token
+          ? html`Registered (scope <code>dataProvider</code> is <code>api/users</code>, request went to <code>api/register</code>).`
+          : html`<p class="text-neutral-500">
+              <code>dataProvider=${usersListEndpoint.path}</code> but
+              <code>endPoint=${registerEndpoint.path}</code> on
+              <code>sonic-submit</code>.
+            </p>`}
+      </div>
+    `;
+  }
+}

package/src/docs/example/docs-toggle-demos.ts

@@ -0,0 +1,73 @@
+import { html, LitElement } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import { subscribe } from "@supersoniks/concorde/core/decorators/Subscriber";
+import { tailwind } from "../tailwind";
+import {
+  docsToggleLoaderFormKey,
+  docsToggleVisibilityKey,
+} from "./docs-provider-keys";
+
+import "../../core/components/functional/if/if";
+import "../../core/components/ui/form/checkbox/checkbox";
+import "../../core/components/ui/image/image";
+import "../../core/components/ui/loader/loader";
+
+const isChecked = (v: unknown) =>
+  v === true || v === "true" || v === 1 || v === "1";
+
+@customElement("docs-toggle-if-demo")
+export class DocsToggleIfDemo extends LitElement {
+  static styles = [tailwind];
+
+  @subscribe(docsToggleVisibilityKey.togglePlan)
+  @state()
+  togglePlan = "";
+
+  render() {
+    const show = isChecked(this.togglePlan);
+    return html`
+      <div formDataProvider=${docsToggleVisibilityKey.path}>
+        <sonic-checkbox
+          label="Show evacuation plan"
+          name="togglePlan"
+          unique
+          checked
+          value="true"
+        ></sonic-checkbox>
+        <sonic-if .condition=${show} class="mt-4 block">
+          <sonic-image
+            src="https://www.thebaron.info/assets/mail/concorde-evacuation.jpg"
+            rounded="md"
+            ratio="654/463"
+          ></sonic-image>
+        </sonic-if>
+      </div>
+    `;
+  }
+}
+
+@customElement("docs-toggle-loader-demo")
+export class DocsToggleLoaderDemo extends LitElement {
+  static styles = [tailwind];
+
+  @subscribe(docsToggleLoaderFormKey.toggleLoader)
+  @state()
+  toggleLoader = "";
+
+  render() {
+    const show = isChecked(this.toggleLoader);
+    return html`
+      <div formDataProvider=${docsToggleLoaderFormKey.path}>
+        <sonic-checkbox
+          label="Show fixed loader"
+          name="toggleLoader"
+          unique
+          value="true"
+        ></sonic-checkbox>
+        <sonic-if .condition=${show}>
+          <sonic-loader></sonic-loader>
+        </sonic-if>
+      </div>
+    `;
+  }
+}

package/src/docs/example/docs-user-two-scopes.ts

@@ -0,0 +1,37 @@
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import { docsUserScopeAKey, docsUserScopeBKey } from "./docs-provider-keys";
+import { tailwind } from "../tailwind";
+import "./decorators-demo-init";
+import "./users";
+
+import "../../core/components/ui/divider/divider";
+
+@customElement("docs-user-two-scopes")
+export class DocsUserTwoScopes extends LitElement {
+  static styles = [tailwind];
+
+  render() {
+    return html`
+      <div class="grid md:grid-cols-2 gap-6">
+        <section>
+          <sonic-divider align="left">Scope A — docsUserScopeA</sonic-divider>
+          <div dataProvider="docsUserScopeA">
+            <docs-user></docs-user>
+          </div>
+        </section>
+        <section>
+          <sonic-divider align="left">Scope B — ${docsUserScopeBKey.path}</sonic-divider>
+          <div dataProvider=${docsUserScopeBKey.path}>
+            <docs-user></docs-user>
+          </div>
+        </section>
+      </div>
+      <p class="mt-4 text-sm text-neutral-500">
+        Same <code>docs-user</code> component: each instance reads the nearest
+        ancestor <code>dataProvider</code> via <code>@ancestorAttribute</code>
+        and <code>docsUserRowKey</code>.
+      </p>
+    `;
+  }
+}

package/src/docs/example/docs-users-list.ts

@@ -0,0 +1,71 @@
+import { html, LitElement, nothing } from "lit";
+import { customElement } from "lit/decorators.js";
+import { tailwind } from "../tailwind";
+import { Endpoint } from "@supersoniks/concorde/core/utils/endpoint";
+import { DOCS_MOCK_REQRES_SERVICE } from "../mock-api/urls";
+
+const usersListEndpoint = new Endpoint<unknown>("api/users");
+import type { DocsUserData } from "./users";
+import "../../core/components/functional/list/list";
+import "../../core/components/ui/image/image";
+import "../../core/components/ui/button/button";
+import "../../core/components/ui/icon/icon";
+import "../../core/components/ui/badge/badge";
+
+@customElement("docs-users-list")
+export class DocsUsersList extends LitElement {
+  static styles = [tailwind];
+
+  private items = ({ id, avatar, first_name, last_name, email }: DocsUserData) =>
+    html`<div
+      class="flex items-center gap-3 rounded-md hover:bg-neutral-50 -mx-2 p-2"
+    >
+      <sonic-image
+        src=${avatar}
+        rounded="md"
+        ratio="1/1"
+        class="w-16 block"
+      ></sonic-image>
+      <div>
+        <div>
+          ${first_name} <span class="font-bold">${last_name}</span>
+        </div>
+        <div class="text-sm text-neutral-400">${email}</div>
+      </div>
+      <div class="ml-auto relative">
+        ${id === "2" || id === "5"
+          ? html`<sonic-badge
+              type="danger"
+              size="2xs"
+              class="absolute left-0 -top-1 z-10"
+              >${id}</sonic-badge
+            >`
+          : nothing}
+        <sonic-button
+          href=${email ? `mailto:${email}` : undefined}
+          size="sm"
+          variant="outline"
+          shape="circle"
+          class="relative"
+          icon
+        >
+          <sonic-icon library="iconoir" name="chat-bubble"></sonic-icon>
+        </sonic-button>
+      </div>
+    </div>`;
+
+  render() {
+    return html`
+      <div serviceURL=${DOCS_MOCK_REQRES_SERVICE}>
+        <sonic-list
+          fetch
+          dataProvider=${usersListEndpoint.path}
+          key="data"
+          class="grid grid-cols-1 gap-2"
+          .items=${this.items}
+          debug
+        ></sonic-list>
+      </div>
+    `;
+  }
+}