@aastrika/ai-elements 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,130 @@ see at a glance what to expect when they upgrade.
 Versions follow semver: a **minor** adds something, a **patch** fixes something,
 and neither removes anything a host was using.
 
+## 0.5.0
+
+A visual pass over all three elements. Nothing a host calls has changed — same
+tags, same attributes, same events — but the elements look different, so this is
+a minor rather than a patch.
+
+**Changed**
+- The accent is blue (`#0EA5E9`), not gold. A host that sets `--aastrika-primary`
+  already overrides it and sees no change; a host that took our default gets the
+  new one
+- Neutrals are cool rather than warm, so the elements sit on a white or pale
+  page without a cream cast
+- A type scale replaces ad-hoc sizes, and one easing curve replaces four
+  durations written out by hand
+- Cards, fields and buttons share one raised treatment: a hairline inside the
+  edge, a layered shadow, a 12-18px radius
+- Tables in Reports lay out to a fixed width, so a long content title wraps in
+  its own column instead of pushing the action buttons off the row. The actions
+  column is sized to hold its buttons, and they sit on the row's centre line
+  like every other cell
+- Assessment takes its material on one surface. Pasting links and choosing
+  files are two ways of saying the same thing, so they share a control, and
+  *Read sources* — which consumes both — sits on its toolbar. The picker and
+  the button used to stand side by side at the same size, which read as a
+  choice between them
+- The file dropzone's label sits with its icon at the start of the zone rather
+  than centred in it, so a wide card no longer shows a small label marooned in
+  a lot of empty space
+- Each step's number is joined to the next by a hairline, and step titles are
+  set as headings rather than at body size, so the card stack reads as a
+  sequence rather than as separate panels
+- The heading scale: a 12px eyebrow and a 16px lead paragraph around the title.
+  At 11 and 14 the step from the title to the sentence under it was large
+  enough that the sentence read as small print
+
+**Fixed**
+- A step that is not your turn yet is readable. It was faded with `opacity`,
+  which multiplies through every child and took the headings to roughly 2:1
+  contrast — that reads as broken rather than as pending. The surface recedes
+  now; the words do not
+- A disabled button, input or select keeps legible text. Browsers grey a
+  disabled control's own text with a colour that is not ours, so on a form that
+  starts disabled the labels were harder to read than the placeholder beside
+  them
+- The main action of a step is readable while it waits. It was white text on a
+  38% tint — about 1.9:1 — so the one button the card is asking you to press
+  was the least visible thing on it
+- Cards show the depth they were given. A second rule later in the stylesheet
+  replaced the layered shadow with a 1px one, so every card rendered flat
+
+**Added**
+- `heading="off"` hides an element's own eyebrow and title, for a host that
+  already names the screen in its own chrome. The description is kept either
+  way. Defaults to `"on"`, so a host that says nothing sees no change
+- `<aa-icon>` draws the 16 glyphs the elements use as inline SVG, stroked in
+  `currentColor`. No icon font, no sprite sheet, no network request
+- Content Studio names the stage of a plan while it runs, with elapsed seconds
+  and a bar. A plan takes about a minute; with no feedback the page read as hung
+- `--aastrika-danger`, `--aastrika-danger-line`, `--aastrika-danger-bg` and
+  `--aastrika-console-bg` / `--aastrika-console-fg` make the error and log
+  colours themeable. They were hardcoded, so a host on a dark page could not
+  reach them
+- Every animation is behind `prefers-reduced-motion`
+
+**Unchanged**
+- `--aastrika-gold`, `--aastrika-gold-soft` and `--aastrika-gold-deep` still
+  work. They now alias the primary set and are removed at 1.0
+
+## 0.4.2
+
+**Fixed**
+- The elements now bring their own typeface, text colour and block layout. They
+  read `--aastrika-font`, which was documented as the way to set the typeface
+  but was never actually applied, so on a host with no font of its own the whole
+  feature rendered in the browser's serif default
+- Buttons, inputs and selects inherit that typeface too. Browsers give form
+  controls a font of their own, so they stayed in the browser's face even where
+  the surrounding text was right
+- The style picker fits as many cards as the width allows instead of always two,
+  so a card no longer stretches to hold one very long line on a wide screen
+- The file dropzone keeps the shape of a target rather than stretching into a
+  letterbox with its label marooned in the middle
+- Content Studio locks its form while a plan or a production is running. The
+  fields stayed editable, so a change made mid-run looked accepted but went
+  nowhere — the request had already left
+- A `creator-filter` of only spaces is treated as no filter, rather than
+  filtering the report to a creator who cannot exist
+- "Create **an** assessment", not "a"
+
+**Added**
+- `--aastrika-max-width` sets how wide a feature runs. It replaces a fixed
+  860px, which a host could only override by reaching into our class names
+- `--aastrika-primary`, `--aastrika-primary-soft`, `--aastrika-primary-deep` and
+  `--aastrika-on-primary` name the accent by its role. `--aastrika-gold*` still
+  work and now point at these, so nothing needs changing until 1.0
+
+**Unchanged**
+- The default palette resolves to exactly the same colours as 0.4.1. The two
+  accent variants stay literal rather than mixed from the primary, because no
+  mix reproduces them — deriving would have quietly restyled every consumer
+
+## 0.4.1
+
+**Fixed**
+- This page now renders on npm. The architecture diagram was mermaid, which npm
+  shows as raw source, and the callouts used GitHub alert syntax. No code change
+
+## 0.4.0
+
+**Changed**
+- Generating a quiz now starts the work and polls for it, instead of waiting on
+  one long request. Nothing to change in your code — same tag, same inputs, same
+  `assessmentReady` firing once with the finished set
+
+**Why it matters**
+- No 60-second ceiling: gateways and proxies commonly close a request at one
+  minute, which capped how many languages could be asked for at once
+- The progress shown is the server's own, not an estimate
+- Closing the tab no longer loses the work
+
+**Notes for integrators**
+- Upgrade the service and the package together. A 0.3.0 element cannot read what
+  a 0.4.0 service answers, and the reverse leaves the element waiting
+
 ## 0.3.0
 
 **Added**

package/README.md

@@ -56,7 +56,6 @@ same questions, same answer key, ready to download.
 
 </div>
 
-> [!IMPORTANT]
 > **You also need gateway access.** This package authenticates nobody — your
 > gateway decides. See [Access](#access) for the groups each feature needs.
 
@@ -67,7 +66,6 @@ same questions, same answer key, ready to download.
 | | |
 |---|---|
 | **[The three features](#the-three-features)** | What each element actually does |
-| **[Setup](#setup)** | Install · access · configure · mount |
 | **[Configuration](#configuration)** | The three values, and why two are functions |
 | **[Access](#access)** | Which gateway groups each feature needs |
 | **[Inputs and events](#inputs-and-events)** | Open the form set up, act on the result |
@@ -133,7 +131,6 @@ fixes wording in place; the correct option is shared, so it is set once.
 Totals for videos, assessments, people and estimated spend, split by tool, with
 a searchable table of creators.
 
-> [!WARNING]
 > **Needs `contentAdmin`, and most consumers should not have it.** Spend figures
 > are not for a partner's ordinary users. The service applies no role check of
 > its own — the gateway's ACL is the only thing keeping them apart.
@@ -142,20 +139,6 @@ a searchable table of creators.
 
 ---
 
-## Setup
-
-The [Quick start](#ship-it-in-three-steps) above is the whole integration. What each step
-is actually doing:
-
-| | Step | Notes |
-|---|---|---|
-| **1** | `npm i @aastrika/ai-elements` | No peer dependencies, no framework to match. Any bundler, or none |
-| **2** | Get gateway access | The package authenticates nobody — your gateway decides. See [Access](#access), then ask the Aastrika platform team |
-| **3** | `configure({ ... })` | Once, before the first element renders. Two of the three values are **functions** — see [Configuration](#configuration) |
-| **4** | Write the tag | Registration happens on import, so there is no third step |
-
----
-
 <details>
 <summary><b>React · Angular · Vue · plain HTML</b></summary>
 
@@ -264,40 +247,19 @@ calling it, as above, prevents both.
 
 ## How it fits together
 
-```mermaid
-flowchart LR
-    subgraph host["Your application"]
-        cfg["configure()"]
-        tag["&lt;aastrika-content-studio&gt;"]
-    end
-
-    subgraph pkg["@aastrika/ai-elements"]
-        el["Custom element"]
-        int["Interceptor"]
-    end
-
-    subgraph svc["Aastrika"]
-        gw["Gateway<br/>checks the token"]
-        api["AI service"]
-    end
-
-    cfg -.->|apiBase · auth · creator| int
-    tag --> el
-    el --> int
-    int -->|"Authorization<br/>creator in the body"| gw
-    gw --> api
-    api -.->|JSON| el
-    el -.->|onError| cfg
-
-    classDef a fill:#0F766E,stroke:none,color:#fff
-    classDef b fill:#f1f5f4,stroke:#cbd5d3,color:#16181d
-    class el,int a
-    class cfg,tag,gw,api b
+```
+  Your application                 @aastrika/ai-elements              Aastrika
+  ────────────────                 ─────────────────────              ────────
+  configure() ─────── apiBase ───▶ interceptor ─── Authorization ───▶ gateway
+                      auth              ▲          creator in body       │
+                      creator           │                                ▼
+  <aastrika-… >  ────────────────▶ element ◀────────── JSON ────────  AI service
+                      ▲                 │
+                      └──── onError ────┘
 ```
 
-**Your application supplies three values. The package does the rest** — builds
-every request from `apiBase`, calls your two functions on each one, and renders
-into your page, styled through CSS custom properties.
+Your application supplies three values. The package builds every request from
+`apiBase`, calls your two functions on each one, and renders into your page.
 
 ---
 
@@ -312,6 +274,23 @@ Three values. That is the whole contract.
 | `creator` | **required** | Who is signed into *your* app. A name or email, shown as-is in the usage report |
 | `onError` | optional | Called whenever a request fails, so your monitoring hears about it |
 
+**Pick the `creator` value with some care.** It is stamped on the content when
+it is made and never changes afterwards, it is what the usage report groups by,
+and it is shown to whoever reads that report. So it wants to be a person's name
+— "Asha Kumari" reads well, and a login handle or an id does not.
+
+Two traps worth knowing, both met in the wild:
+
+- **A login handle is not a name.** `creatoruser_if0d` is unreadable, and if you
+  switch to it later, the report treats it as a different person from the name
+  the same user's earlier content was filed under.
+- **Check your email field is not masked.** Some portals return
+  `cr********@yopmail.com` from their profile API. Every user then files content
+  under a near-identical string, and the report cannot tell them apart.
+
+Returning `null` is a fair answer when you have no good name: the service
+applies its own default rather than recording something meaningless.
+
 ### Why two of them are functions
 
 Tokens expire. A string handed over at startup stops working mid-session, and
@@ -325,7 +304,6 @@ getAuthHeaders: async () => ({ Authorization: `Bearer ${await auth.token()}` }),
 The same goes for `creator`: a function lets you switch user without reloading
 the page.
 
-> [!NOTE]
 > **`creator` is attribution, not identity.** It is recorded against whatever
 > the call creates and the usage report groups by it. Nothing verifies it — the
 > gateway decides whether the call is allowed at all.
@@ -348,7 +326,6 @@ needs:
 Deleting anything needs `contentAdmin` as well. Without `contentUpdate` the
 features still work, but the revise step returns 403.
 
-> [!CAUTION]
 > **`generate-video` is the only call that spends real money**, and it sits on a
 > deliberately low rate limit. Users see a cost estimate before triggering it.
 
@@ -428,27 +405,26 @@ All are **starting values** the user can still change.
 | | `default-difficulty` | `mixed`, `easy`, `medium`, `hard` |
 | | `default-translate-into` | Also produce the same questions in these languages, comma-separated: `"ta,or,bn"` |
 | `reports` | `creator-filter` | Opens filtered to one creator |
+| *all three* | `heading` | `off` hides the element's own eyebrow and title. Defaults to `on` |
+
+**`heading="off"`** is for a host whose own chrome already names the screen — a
+breadcrumb or a tab bar — where the element's title would say it a second time.
+The description under the title is kept either way: it says what the feature
+does, which a breadcrumb does not. Use it instead of hiding the title with CSS;
+our class names are ours to rename, and a stylesheet reaching in breaks silently
+when they change.
 
 ```html
-<aastrika-content-studio default-language="kn" default-aspect-ratio="9:16">
-</aastrika-content-studio>
+<!-- your page already shows "AI Studio › Assessment Creation" -->
+<aastrika-assessment heading="off"></aastrika-assessment>
 ```
 
-### One quiz, several languages
-
-`default-translate-into` produces the **same** questions in other languages —
-same order, same options, same answer key — so one answer key marks every
-language and scores compare across them.
-
 ```html
-<aastrika-assessment default-language="hi" default-translate-into="en,mr">
-</aastrika-assessment>
+<aastrika-content-studio default-language="kn" default-aspect-ratio="9:16">
+</aastrika-content-studio>
 ```
 
-The reviewer gets a tab per language. Excel holds every language, one sheet
-each; CSV holds one language at a time.
-
-`assessmentReady` reports what came back:
+### Translations, in the event
 
 ```js
 el.addEventListener('assessmentReady', (e) => {
@@ -459,8 +435,8 @@ el.addEventListener('assessmentReady', (e) => {
 
 `languages` can be shorter than what was asked for. A translation is checked for
 question count, ids, answer key, clinical numbers and script; one that fails is
-dropped rather than stored wrong. What is **not** checked is whether the
-translation reads well — that still needs someone who speaks the language.
+dropped rather than stored wrong. What is **not** checked is whether it reads
+well — that still needs someone who speaks the language.
 
 ### Events
 

package/aastrika-elements.d.ts

@@ -74,6 +74,15 @@ export declare const ready: Promise<unknown>;
 
 /** `<aastrika-content-studio>` — a document becomes a narrated training video. */
 interface AastrikaContentStudioElement extends HTMLElement {
+  /**
+   * `'off'` hides the element's own eyebrow and title. Defaults to `'on'`.
+   *
+   * For a host that already names the screen in its own chrome — a breadcrumb,
+   * a tab bar — where the element's heading would say it a second time. The
+   * description below the title is kept either way: it says what the feature
+   * does, which a breadcrumb does not.
+   */
+  heading?: 'on' | 'off';
   /**
    * `'on'` shows the segment editor for an uploaded video. Defaults to `'off'`.
    *
@@ -117,6 +126,15 @@ interface AastrikaContentStudioElement extends HTMLElement {
 
 /** `<aastrika-assessment>` — source material becomes a validated MCQ set. */
 interface AastrikaAssessmentElement extends HTMLElement {
+  /**
+   * `'off'` hides the element's own eyebrow and title. Defaults to `'on'`.
+   *
+   * For a host that already names the screen in its own chrome — a breadcrumb,
+   * a tab bar — where the element's heading would say it a second time. The
+   * description below the title is kept either way: it says what the feature
+   * does, which a breadcrumb does not.
+   */
+  heading?: 'on' | 'off';
   /** Language the form opens on. */
   defaultLanguage?: string;
   /** How many questions to ask for. */
@@ -157,6 +175,15 @@ interface AastrikaAssessmentElement extends HTMLElement {
 
 /** `<aastrika-reports>` — usage and spend. Needs `contentAdmin` at the gateway. */
 interface AastrikaReportsElement extends HTMLElement {
+  /**
+   * `'off'` hides the element's own eyebrow and title. Defaults to `'on'`.
+   *
+   * For a host that already names the screen in its own chrome — a breadcrumb,
+   * a tab bar — where the element's heading would say it a second time. The
+   * description below the title is kept either way: it says what the feature
+   * does, which a breadcrumb does not.
+   */
+  heading?: 'on' | 'off';
   /** Opens filtered to one creator. The user can still clear it. */
   creatorFilter?: string;