@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/prompt-composer.json

@@ -0,0 +1,498 @@
+{
+  "family": "prompt-composer",
+  "ui": "prompt-composer",
+  "binding": "angular",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Multi-line message input with send and tools."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "raised",
+      "outline",
+      "subtle"
+    ],
+    "submitOn": [
+      "enter",
+      "mod-enter"
+    ],
+    "status": [
+      "ready",
+      "submitted",
+      "streaming",
+      "error"
+    ]
+  },
+  "members": {
+    "promptComposer": {
+      "nativeElement": "form",
+      "defaults": {
+        "size": "md",
+        "variant": "raised",
+        "submitOn": "enter",
+        "status": "ready",
+        "rows": 1,
+        "maxRows": 8,
+        "showCount": false
+      },
+      "capabilities": [
+        "value",
+        "appearance",
+        "size",
+        "status",
+        "loading",
+        "content",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "invalid",
+        "readonly",
+        "loading",
+        "drop-target"
+      ],
+      "parts": [
+        "root",
+        "header",
+        "input",
+        "footer",
+        "action",
+        "attach",
+        "submit"
+      ]
+    }
+  },
+  "docs": {
+    "promptComposer": {
+      "imports": {
+        "source": "import {\n  providePromptComposerDefaults,\n  SlPromptComposer,\n  SlPromptComposerAction,\n  SlPromptComposerAttach,\n  SlPromptComposerFooter,\n  SlPromptComposerHeader,\n  SlPromptComposerInput,\n  SlPromptComposerSubmit,\n} from '@slotted/angular/prompt-composer';",
+        "selector": "form[slPromptComposer]",
+        "exportAs": "slPromptComposer"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "form[slPromptComposer], the consumer’s own form",
+          "required": true,
+          "purpose": "The frame: border, ground, lift and the focus ring while the value has focus. Carries data-ui=\"prompt-composer\", data-size, data-variant, data-status, and data-disabled, data-invalid, data-readonly, data-loading and data-drop-target. A press on its padding puts the caret in the value; files dropped on it are handed to (attach)."
+        },
+        {
+          "part": "header",
+          "element": "any element carrying slPromptComposerHeader",
+          "required": false,
+          "purpose": "The band above the value: attachments, a quoted reply, a context chip. It wraps, and a strip of attachments scrolls inside it rather than crossing the frame."
+        },
+        {
+          "part": "input",
+          "element": "textarea[slPromptComposerInput]",
+          "required": true,
+          "purpose": "The value. Grows from rows to maxRows with field-sizing, then scrolls; each paragraph takes its own direction. Enter, Mod+Enter and Shift+Enter are described in the keyboard scene. It is the ControlValueAccessor, so a reactive form binds there; exportAs slPromptComposerInput reaches inputElement."
+        },
+        {
+          "part": "footer",
+          "element": "any element carrying slPromptComposerFooter",
+          "required": false,
+          "purpose": "The band below the value: tools on the start, the send held at the end by an automatic margin."
+        },
+        {
+          "part": "action",
+          "element": "button[slPromptComposerAction]",
+          "required": false,
+          "purpose": "A button of the consumer’s in a band: a model menu, a tool, Cancelar. Round when named by aria-label, a pill when named by its words; aria-expanded=\"true\" keeps it pressed while its menu is open."
+        },
+        {
+          "part": "attach",
+          "element": "button[slPromptComposerAttach]",
+          "required": false,
+          "purpose": "Opens the file chooser with the composer’s accept and multiple, and hands the choice to (attach) with reason \"pointer\"."
+        },
+        {
+          "part": "submit",
+          "element": "button[slPromptComposerSubmit]",
+          "required": false,
+          "purpose": "The send: a round accent disc named by the label for its status — Send, Sending, Stop, Retry — or a pill named by the words given to it. A busy ring while submitted, a stop square inside the ring while streaming, a retry turn after an error."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slPromptComposer",
+          "description": "Present means the consumer owns the value. defaultValue is the uncontrolled half"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slPromptComposer",
+          "description": "What an uncontrolled composer starts from"
+        },
+        {
+          "name": "status",
+          "type": "'ready' | 'submitted' | 'streaming' | 'error'",
+          "defaultValue": "ready",
+          "appliesTo": "slPromptComposer",
+          "description": "Where the request stands. submitted is busy, streaming turns the send into a stop, error into a retry"
+        },
+        {
+          "name": "submitOn",
+          "type": "'enter' | 'mod-enter'",
+          "defaultValue": "enter",
+          "appliesTo": "slPromptComposer, providePromptComposerDefaults",
+          "description": "Which key sends. Shift+Enter always breaks a line; Mod+Enter always sends"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slPromptComposer, providePromptComposerDefaults",
+          "description": "The control step, read from the field first"
+        },
+        {
+          "name": "variant",
+          "type": "'raised' | 'outline' | 'subtle'",
+          "defaultValue": "raised",
+          "appliesTo": "slPromptComposer, providePromptComposerDefaults",
+          "description": "raised is the chat surface; outline and subtle sit inside a form"
+        },
+        {
+          "name": "canSubmit",
+          "type": "boolean",
+          "defaultValue": "the value is not blank",
+          "appliesTo": "slPromptComposer",
+          "description": "Whether the send is available; an application with attachments ready says true"
+        },
+        {
+          "name": "accept / maxSize / maxFiles / multiple",
+          "type": "string / number / number / boolean",
+          "defaultValue": "— / — / — / true",
+          "appliesTo": "slPromptComposer",
+          "description": "The selection rules upload applies, for the paperclip, a paste and a drop"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slPromptComposer",
+          "description": "Unstated rather than false, so the composer defers to its field. The native attribute on the textarea; the paperclip and the send leave the tab order with it"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slPromptComposer",
+          "description": "The value stays focusable and copyable; the paperclip and the send are withdrawn"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slPromptComposer",
+          "description": "aria-invalid on the textarea and the danger edge on the frame"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "from the field",
+          "appliesTo": "slPromptComposer",
+          "description": "aria-required on the textarea, never the native attribute, which would engage constraint validation"
+        },
+        {
+          "name": "loading",
+          "type": "derived",
+          "defaultValue": "false",
+          "appliesTo": "slPromptComposer",
+          "description": "data-loading on the frame while status is submitted or streaming; it is read from status, never set"
+        },
+        {
+          "name": "rows",
+          "type": "number",
+          "defaultValue": "1",
+          "appliesTo": "slPromptComposerInput",
+          "description": "The fewest lines the value shows"
+        },
+        {
+          "name": "maxRows",
+          "type": "number",
+          "defaultValue": "8",
+          "appliesTo": "slPromptComposerInput",
+          "description": "The most lines it grows to before it scrolls"
+        },
+        {
+          "name": "showCount",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slPromptComposerInput",
+          "description": "Publishes the length of the value to the field, which draws the count"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<PromptComposerMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slPromptComposer",
+          "description": "Words laid over the language in force, key by key: what the send says in each status, what is announced, and the paperclip’s name"
+        }
+      ],
+      "composition": [
+        {
+          "name": "exportAs",
+          "type": "slPromptComposer, slPromptComposerInput, slPromptComposerAction",
+          "defaultValue": "—",
+          "appliesTo": "the directives",
+          "description": "Reach the instance from a template; slPromptComposerInput.inputElement is the native textarea"
+        },
+        {
+          "name": "button[slPromptComposerAction]",
+          "type": "directive",
+          "defaultValue": "type=\"button\"",
+          "appliesTo": "a band",
+          "description": "A button of the consumer’s; slMenuTriggerFor or slTooltipTrigger sit on the same element, and the part is written back after the first render"
+        },
+        {
+          "name": "providePromptComposerDefaults",
+          "type": "(defaults: Partial<PromptComposerDefaults>) => Provider",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The decisions an application takes once"
+        },
+        {
+          "name": "ControlValueAccessor",
+          "type": "formControl, ngModel",
+          "defaultValue": "—",
+          "appliesTo": "slPromptComposerInput",
+          "description": "The value belongs in a reactive or template-driven form as it stands"
+        }
+      ],
+      "events": [
+        {
+          "name": "(valueChange)",
+          "payload": "ChangeRequest<string>",
+          "when": "On slPromptComposerInput, before the value moves: reason \"keyboard\" for an edit, \"submit\" for the clearing after an accepted send. cancel() refuses the move."
+        },
+        {
+          "name": "(valueSubmit)",
+          "payload": "ChangeRequest<string>",
+          "when": "On slPromptComposer, before the message is sent from Enter, Mod+Enter or the send — reason \"keyboard\" or \"pointer\". cancel() keeps the value; otherwise it is cleared."
+        },
+        {
+          "name": "(stop)",
+          "payload": "PromptComposerStopEvent — { reason, source }",
+          "when": "The stop button, while status is \"streaming\". “Stopped” is announced."
+        },
+        {
+          "name": "(attach)",
+          "payload": "PromptComposerAttachEvent — { files, reason, rejected, source }",
+          "when": "Files from the paperclip (\"pointer\"), a paste (\"paste\") or a drop (\"drop\"), after accept, maxSize, maxFiles and multiple."
+        },
+        {
+          "name": "ControlValueAccessor",
+          "payload": "the form’s own value and touched state",
+          "when": "On slPromptComposerInput, whenever the value moves and the request was not cancelled — including the clearing after a send — and on blur for touched."
+        }
+      ],
+      "accessibility": [
+        "There is no APG pattern for a composer; the textarea supplies the textbox role, the field supplies the name, and the root is the consumer’s form, so Enter in the value and the send button are the platform’s submission.",
+        "The send is named by the label for its status — Send, Sending, Stop, Retry — and the change of name is what a screen reader hears when the request moves; “Sending” and “Stopped” are announced once through the shared live announcer.",
+        "While the request is submitted the send is aria-disabled rather than disabled, so focus is not thrown out of it; Enter in the value does nothing until the status returns.",
+        "Enter never sends while an input method is composing (isComposing, keyCode 229): in Japanese and Chinese Enter confirms the composition.",
+        "The attachments are the application’s list and are drawn with attachment, which owns their names, their removal and the focus after a removal. Refused files are reported in onAttach so the application can say why.",
+        "The bands are not an APG toolbar: each button keeps its own tab stop, because there are few of them and they do different things."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-strong",
+    "--slotted-border-subtle",
+    "--slotted-border-width-medium",
+    "--slotted-border-width-thin",
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-inner-size-lg",
+    "--slotted-control-inner-size-md",
+    "--slotted-control-inner-size-sm",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-shadow",
+    "--slotted-control-shadow-focus-geometry",
+    "--slotted-control-surface",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-medium",
+    "--slotted-duration-short",
+    "--slotted-easing-enter",
+    "--slotted-easing-exit",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-weight-medium",
+    "--slotted-line-height-md",
+    "--slotted-prompt-composer-action-active-background",
+    "--slotted-prompt-composer-action-color",
+    "--slotted-prompt-composer-action-hover-background",
+    "--slotted-prompt-composer-action-label-color",
+    "--slotted-prompt-composer-background",
+    "--slotted-prompt-composer-border-color",
+    "--slotted-prompt-composer-caret-color",
+    "--slotted-prompt-composer-color",
+    "--slotted-prompt-composer-disabled-background",
+    "--slotted-prompt-composer-disabled-border-color",
+    "--slotted-prompt-composer-disabled-color",
+    "--slotted-prompt-composer-drop-background",
+    "--slotted-prompt-composer-drop-border-color",
+    "--slotted-prompt-composer-hover-border-color",
+    "--slotted-prompt-composer-invalid-border-color",
+    "--slotted-prompt-composer-invalid-edge-width",
+    "--slotted-prompt-composer-invalid-focus-ring-color",
+    "--slotted-prompt-composer-line-height",
+    "--slotted-prompt-composer-max-rows",
+    "--slotted-prompt-composer-placeholder-color",
+    "--slotted-prompt-composer-radius",
+    "--slotted-prompt-composer-raised-focus-shadow",
+    "--slotted-prompt-composer-raised-shadow",
+    "--slotted-prompt-composer-readonly-background",
+    "--slotted-prompt-composer-rows",
+    "--slotted-prompt-composer-selection-background",
+    "--slotted-prompt-composer-shadow",
+    "--slotted-prompt-composer-submit-active-background",
+    "--slotted-prompt-composer-submit-background",
+    "--slotted-prompt-composer-submit-color",
+    "--slotted-prompt-composer-submit-disabled-background",
+    "--slotted-prompt-composer-submit-hover-background",
+    "--slotted-prompt-composer-subtle-background",
+    "--slotted-prompt-composer-subtle-border-color",
+    "--slotted-radius-full",
+    "--slotted-radius-lg",
+    "--slotted-radius-xs",
+    "--slotted-shadow-lg",
+    "--slotted-shadow-md",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-surface-sunken",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-on-solid",
+    "--slotted-tone-accent-solid",
+    "--slotted-tone-accent-solid-active",
+    "--slotted-tone-accent-solid-hover",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "The chat composer with the controls below the canvas: write, press Enter, and the value clears once the send is accepted. Switch the status to see the send turn into a busy ring, a stop and a retry.",
+      "language": "html",
+      "source": "<form slPromptComposer [status]=\"status()\" (valueSubmit)=\"send($event.value)\" (stop)=\"abort()\">\n  <textarea\n    slPromptComposerInput\n    aria-label=\"Mensagem\"\n    placeholder=\"Pergunte ao assistente\"\n  ></textarea>\n  <div slPromptComposerFooter>\n    <button slPromptComposerAttach></button>\n    <button slPromptComposerSubmit></button>\n  </div>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "chat",
+      "title": "An assistant that answers while you wait",
+      "note": "Send a question: the status goes to submitted, then streaming, and back to ready when the answer ends — the send turns into a ring, then a stop inside the ring. Press stop and the answer is cut short. The model is a menu on an action.",
+      "language": "html",
+      "source": "<form\n  slPromptComposer\n  [status]=\"chat.status()\"\n  (valueSubmit)=\"chat.send($event.value)\"\n  (stop)=\"chat.stop()\"\n>\n  <textarea\n    slPromptComposerInput\n    aria-label=\"Mensagem\"\n    placeholder=\"Pergunte ao assistente\"\n  ></textarea>\n  <div slPromptComposerFooter>\n    <button slPromptComposerAttach></button>\n    <button slPromptComposerAction [slMenuTriggerFor]=\"models\">{{ model() }}</button>\n    <button slPromptComposerSubmit></button>\n  </div>\n</form>\n<sl-menu #models>\n  <sl-menu-radio-group [(value)]=\"model\">\n    <button slMenuRadioItem value=\"Claude Opus\">Claude Opus</button>\n  </sl-menu-radio-group>\n</sl-menu>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "comment",
+      "title": "A comment box in a form",
+      "note": "The outline variant keeps a one-line control’s geometry beside the other fields. The send is named by its word, Comentar; Cancelar is an action. Enter breaks a line here, because a comment has paragraphs: Mod+Enter sends.",
+      "language": "html",
+      "source": "<form slPromptComposer variant=\"outline\" submitOn=\"mod-enter\" (valueSubmit)=\"post($event.value)\">\n  <textarea slPromptComposerInput aria-label=\"Comentário\" rows=\"3\"></textarea>\n  <div slPromptComposerFooter>\n    <button slPromptComposerAction (click)=\"close()\">Cancelar</button>\n    <button slPromptComposerSubmit>Comentar</button>\n  </div>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "attachments",
+      "title": "Attaching by the paperclip, a paste and a drop",
+      "note": "Choose files, paste a screenshot into the value, or drag files over the frame — it washes in the accent and draws a dashed edge before you let go. Images and PDFs up to 5 MB are accepted; anything else is listed as refused. The attachments are the application’s list, drawn with attachment.",
+      "language": "html",
+      "source": "<form\n  slPromptComposer\n  accept=\"image/*,application/pdf\"\n  [maxSize]=\"5000000\"\n  [canSubmit]=\"files().length > 0 || undefined\"\n  (attach)=\"add($event.files, $event.rejected)\"\n>\n  <div slPromptComposerHeader>\n    <ul slAttachmentGroup layout=\"strip\" size=\"sm\" aria-label=\"Anexos\">\n      @for (file of files(); track file.name) {\n        <li slAttachment [file]=\"file\" removable (remove)=\"remove(file)\">\n          <span slAttachmentPreview></span>\n          <div slAttachmentBody><span slAttachmentFilename></span></div>\n          <div slAttachmentActions><button slAttachmentRemove></button></div>\n        </li>\n      }\n    </ul>\n  </div>\n  <textarea slPromptComposerInput aria-label=\"Mensagem\"></textarea>\n  <div slPromptComposerFooter>\n    <button slPromptComposerAttach></button>\n    <button slPromptComposerSubmit></button>\n  </div>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "status",
+      "title": "The four statuses of the request",
+      "note": "ready sends; submitted is busy and refuses Enter; streaming stops; error offers a retry. The status is the application’s, because only the application knows whether an answer is on its way.",
+      "language": "html",
+      "source": "<form slPromptComposer status=\"ready\"></form>\n<form slPromptComposer status=\"submitted\"></form>\n<form slPromptComposer status=\"streaming\" (stop)=\"abort()\"></form>\n<form slPromptComposer status=\"error\"></form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The step the composer sits at",
+      "note": "Three steps of the control scale, and three variants: raised lifts a chat surface off the page, outline and subtle sit inside a form. Switch the toolbar to dense and each step shrinks whole.",
+      "language": "html",
+      "source": "<form slPromptComposer size=\"sm\"></form>\n<form slPromptComposer size=\"md\" variant=\"outline\"></form>\n<form slPromptComposer size=\"lg\" variant=\"subtle\"></form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Invalid, read-only and disabled",
+      "note": "Invalid takes the danger edge and the field’s message says why; read-only keeps the value legible and copyable and withdraws the send; disabled mutes everything to the measured colour and takes the composer out of the tab order.",
+      "language": "html",
+      "source": "<div slField [invalid]=\"true\">\n  <label slFieldLabel>Mensagem</label>\n  <form slPromptComposer>\n    <textarea slPromptComposerInput></textarea>\n  </form>\n  <p slFieldError>A mensagem passa de 2 000 caracteres.</p>\n</div>\n<form slPromptComposer>\n  <textarea slPromptComposerInput readOnly defaultValue=\"Arquivado\"></textarea>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Long, translated and right-to-left",
+      "note": "A long message grows to maxRows and then scrolls, with the band still under the thumb. Each paragraph takes its own direction, so an Arabic line and a Portuguese line sit in one value without either ending at the wrong margin.",
+      "language": "html",
+      "source": "<form slPromptComposer>\n  <textarea slPromptComposerInput aria-label=\"Mensagem\" maxRows=\"6\"></textarea>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and reaching past it",
+      "note": "providePromptComposerDefaults carries the variant and the send key, and the words come from the language in force; exportAs reaches the textarea, which already has select(); the value binds to a reactive form.",
+      "language": "html",
+      "source": "<form slPromptComposer>\n  <textarea\n    slPromptComposerInput\n    #mensagem=\"slPromptComposerInput\"\n    [formControl]=\"texto\"\n  ></textarea>\n  <div slPromptComposerFooter>\n    <button slPromptComposerAction (click)=\"mensagem.inputElement.select()\">Selecionar</button>\n    <button slPromptComposerSubmit></button>\n  </div>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the keyboard does",
+      "note": "Enter sends and Shift+Enter breaks a line; with submitOn=\"mod-enter\" Enter breaks a line and Mod+Enter sends. Nothing is sent while an input method is composing, because there Enter confirms the composition. Escape is not bound.",
+      "language": "html",
+      "source": "<form slPromptComposer submitOn=\"enter\"></form>\n<form slPromptComposer submitOn=\"mod-enter\"></form>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}