@edvizion/astro-components 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# @edvizion/astro-components
+
+Shared Astro components for Edvizion apps.
+
+- [`<SchoolSearch>`](#schoolsearch) — school picker backed by the Edvizion School Directory
+- [`<EdvizionTheme>`](#theming) — shared design tokens for every component
+
+## SchoolSearch
+
+```astro
+---
+import { SchoolSearch } from '@edvizion/astro-components';
+---
+<form>
+  <SchoolSearch
+    name="schoolId"
+    required
+    defaultState="AZ"
+    stateLabel="School of Attendance State"
+    schoolLabel="School of Attendance Name"
+  />
+  <button>Save</button>
+</form>
+```
+
+The user picks a US state (50 + DC), types a school name or city, and presses
+**Enter** or **Search**. Nothing is fetched while typing. Picking a result sets
+the value to that school's `edvizionId`.
+
+Requests go to `https://api.edvizion.com/schools/*` with no `Authorization`
+header — Edvizion Auth injects the token.
+
+### Recommending a missing school
+
+After any search, the user sees **"Can't find your school? Recommend it"**. That
+opens an inline panel (school name, prefilled from the search, plus optional
+notes) which POSTs `{ name, state, notes }` to `/schools/recommendations`.
+
+On a **202** the component's value becomes **`sch_00000000-0000-0000-0000-000000000000`** and the card
+reads "Recommended — pending review". Recommendations are reviewed by a person
+in a Google Space and never enter the directory, so there is no real
+`edvizionId` yet. The submitted name and state are on
+`picker.selectedSchool.recommendation`:
+
+```js
+picker.value;                           // "sch_00000000-0000-0000-0000-000000000000"
+picker.selectedSchool.recommendation;   // { name, state, notes, requestId, submittedAt }
+```
+
+A native form post only carries `sch_00000000-0000-0000-0000-000000000000`, so if your backend needs the
+recommended name, read it from `selectedSchool` (or the `edv-recommend` event)
+and send it along.
+
+Any failure keeps the panel open with the user's text so they can retry. A 502
+means the recommendation reached nobody.
+
+Hide the feature with `recommend={false}`. `RECOMMENDED_SCHOOL_ID` is exported
+for comparisons.
+
+### Props
+
+| prop | default | |
+| --- | --- | --- |
+| `name` | — | Form field name the `edvizionId` is submitted under |
+| `required` | `false` | Requires both a state and a school |
+| `disabled` | `false` | Also disabled by a disabled `<fieldset>` |
+| `defaultState` | none | USPS code, case-insensitive. Unsupported codes are ignored with a warning |
+| `stateLabel` | `"State"` | Label for the state select |
+| `schoolLabel` | `"School"` | Label for the search box |
+| `placeholder` | `"School name or city"` | |
+| `hint` | `"Search by school name or city, then press Enter."` | |
+| `limit` | `20` | Results per page (max 100). "Show more results" pages beyond this |
+| `value` / `valueName` | — | Pre-selected school for edit forms (`valueName` is the display name). `sch_00000000-0000-0000-0000-000000000000` shows as pending review |
+| `endpoint` | production API | Override the search endpoint (e.g. staging) |
+| `recommend` | `true` | Offer "Recommend it" when a school can't be found |
+| `recommendEndpoint` | production API | Override the recommendation endpoint |
+| `form` | — | Associate with a form by id when not nested inside it |
+
+Any other attribute (`id`, `class`, `data-*`, …) is passed to the element.
+
+### Reading value and validity
+
+`<SchoolSearch>` renders an `<edv-school-search>` element that is a real
+form-associated control, so you read it exactly like an `<input>`.
+
+**Through the form** — nothing special:
+
+```js
+const form = document.querySelector('form');
+new FormData(form).get('schoolId'); // "sch_0a19…" or null
+form.checkValidity();               // false until a state and school are chosen
+form.elements.schoolId;             // the <edv-school-search> element
+```
+
+The internal state select and search box are never submitted; only the
+`edvizionId` is. Native form submission is blocked while it is invalid, and the
+component shows inline errors.
+
+**From the element directly:**
+
+```js
+const picker = document.querySelector('edv-school-search');
+
+picker.value;             // "sch_…" or ""
+picker.selectedSchool;    // { edvizionId, name, city, state } | null
+picker.state;             // "AZ" or ""
+picker.validity;          // ValidityState — .valid, .valueMissing, .customError
+picker.validationMessage; // "Select a state." | "Search for and select a school." | custom
+picker.checkValidity();
+picker.reportValidity();
+picker.setCustomValidity('That school is not eligible.'); // '' to clear
+
+picker.state = 'NV';                  // programmatic; clears the selection
+picker.selectSchool({ edvizionId, name, city, state });
+```
+
+**Events** (all bubble from `<edv-school-search>`):
+
+| event | when |
+| --- | --- |
+| `input`, `change` | the selected school changes (chosen, cleared, or cleared by a state change). Read `event.target.value` |
+| `edv-search` | results loaded. `detail: { query, state, offset, results }` |
+| `edv-search-error` | a search failed. `detail: { status, code, requestId, message }` |
+| `edv-recommend` | a recommendation was accepted (202). `detail: { name, state, notes, requestId, submittedAt }` |
+| `edv-recommend-error` | a recommendation failed. Same `detail` shape as `edv-search-error` |
+
+Typing in the search box does **not** fire `input` on the component; its value
+only changes when a school is selected.
+
+In TypeScript, `document.querySelector('edv-school-search')` is typed as
+`EdvSchoolSearchElement`.
+
+### Accessibility
+
+Labelled controls, a polite live region for search status, results as an ARIA
+listbox (↓ from the search box, ↑/↓/Home/End, Enter or Space to choose, Esc to
+return), focus moved to the "Change school" button after selecting, and inline
+errors tied to the controls with `aria-invalid` / `aria-describedby`. Axe runs
+in the e2e suite.
+
+## Theming
+
+Every component reads `--edv-*` CSS custom properties, with built-in defaults,
+so they look right with no setup. Custom properties inherit through shadow DOM,
+so one theme restyles every component.
+
+```astro
+---
+import { EdvizionTheme } from '@edvizion/astro-components';
+---
+<!-- Whole page -->
+<EdvizionTheme global theme={{ colorPrimary: '#0f766e', radiusSmall: '0' }} />
+
+<!-- Or just a subtree -->
+<EdvizionTheme theme={{ colorPrimary: '#7c3aed' }}>
+  <SchoolSearch name="school" />
+</EdvizionTheme>
+```
+
+Or set the properties in any stylesheet:
+
+```css
+:root { --edv-color-primary: #0f766e; --edv-font-family: Inter, sans-serif; }
+```
+
+The token list is `TOKEN_PROPERTIES` in [src/theme/tokens.ts](src/theme/tokens.ts).
+For one-off overrides beyond tokens, components expose `::part()`:
+
+```css
+edv-school-search::part(search-button) { text-transform: uppercase; }
+```
+
+SchoolSearch parts: `root`, `state-field`, `school-field`, `label`, `select`,
+`input`, `button`, `search-button`, `change-button`, `more-button`, `hint`,
+`error`, `status`, `results`, `option`, `option-name`, `option-meta`,
+`selection`, `selection-name`, `selection-meta`, `recommend-prompt`,
+`recommend-button`, `recommend`, `recommend-input`, `textarea`,
+`recommend-notes`, `recommend-submit`, `recommend-cancel`.
+
+New components should build their shadow styles on `baseComponentStyles` and
+`cssVar()` from `src/theme/` so they pick up the same tokens.
+
+## Development
+
+```bash
+npm run dev        # playground at http://localhost:4391
+npm run test:e2e   # Playwright: Chromium, Firefox, WebKit
+npm run check      # astro check (TypeScript)
+```
+
+The e2e suite mocks both endpoints with `page.route`, so it needs no token and
+never hits production. Fixture pages live in `playground/pages/fixtures/`. It
+runs its own server on port 4399, so it can run alongside `npm run dev`.
+
+### Trying it against the real API
+
+`localhost` is on the API's CORS allow-list. Start `npm run dev`, open
+http://localhost:4391, and paste this into the DevTools console. It stands in
+for Edvizion Auth by adding your token to requests to `api.edvizion.com`, and it
+prompts for the token so the token never lands in your console history:
+
+```js
+(() => {
+  const token = prompt('Edvizion Cognito JWT (ID or access token)')?.trim().replace(/^Bearer\s+/i, '');
+  if (!token) return console.warn('No token entered; fetch left unchanged.');
+  const realFetch = (window.__edvRealFetch ??= window.fetch.bind(window));
+  window.fetch = (input, init = {}) => {
+    const url = new URL(input instanceof Request ? input.url : String(input), location.href);
+    if (url.origin !== 'https://api.edvizion.com') return realFetch(input, init);
+    const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
+    headers.set('authorization', `Bearer ${token}`);
+    return realFetch(input, { ...init, headers });
+  };
+  try {
+    const { exp } = JSON.parse(atob(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')));
+    console.info(`Edvizion token injected. Expires ${new Date(exp * 1000).toLocaleString()}. Reload the page to remove it.`);
+  } catch {
+    console.info('Edvizion token injected. Reload the page to remove it.');
+  }
+})();
+```
+
+Recommendations sent this way are **real**: they post to the review Google
+Space.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@edvizion/astro-components",
+  "version": "0.1.0",
+  "description": "Shared Astro components for Edvizion apps.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "exports": {
+    ".": "./src/index.ts",
+    "./SchoolSearch.astro": "./src/components/SchoolSearch/SchoolSearch.astro",
+    "./EdvizionTheme.astro": "./src/theme/EdvizionTheme.astro",
+    "./school-search-element": "./src/components/SchoolSearch/school-search-element.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "astro-component",
+    "withastro"
+  ],
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "check": "astro check",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui"
+  },
+  "peerDependencies": {
+    "astro": ">=5"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@axe-core/playwright": "^4.13.0",
+    "@playwright/test": "^1.63.0",
+    "@types/node": "^26.6.3",
+    "astro": "^7.3.5",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/components/SchoolSearch/SchoolSearch.astro

@@ -0,0 +1,98 @@
+---
+/**
+ * School picker backed by the Edvizion School Directory. Behaves like a
+ * native form control: submits the chosen school's `edvizionId` under `name`,
+ * participates in form validation, reset, and disabled fieldsets.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import { normalizeStateCode } from './us-states';
+
+interface Props extends Omit<HTMLAttributes<'div'>, 'slot'> {
+  /** Form field name the `edvizionId` is submitted under. */
+  name?: string;
+  required?: boolean;
+  disabled?: boolean;
+  /** Pre-selected USPS state code, e.g. "AZ". Case-insensitive. */
+  defaultState?: string;
+  /** Label for the state select. Default: "State". e.g. "School of Attendance State". */
+  stateLabel?: string;
+  /** Label for the school search field. Default: "School". e.g. "School of Attendance Name". */
+  schoolLabel?: string;
+  placeholder?: string;
+  /** Helper text under the search field. */
+  hint?: string;
+  /** Results per page (max 100). Default: 20. */
+  limit?: number;
+  /** Override the search endpoint (e.g. a staging API). */
+  endpoint?: string;
+  /**
+   * Let users recommend a school that search can't find. On success the value
+   * becomes `sch_00000000-0000-0000-0000-000000000000`. Default: true.
+   */
+  recommend?: boolean;
+  /** Override the recommendation endpoint. */
+  recommendEndpoint?: string;
+  /** Pre-selected school `edvizionId` (for edit forms; may be `sch_00000000-0000-0000-0000-000000000000`). */
+  value?: string;
+  /** Display name for a pre-selected `value`. */
+  valueName?: string;
+  /** Associate with a form by id when not nested inside it. */
+  form?: string;
+}
+
+const {
+  name,
+  required,
+  disabled,
+  defaultState,
+  stateLabel,
+  schoolLabel,
+  placeholder,
+  hint,
+  limit,
+  endpoint,
+  recommend = true,
+  recommendEndpoint,
+  value,
+  valueName,
+  ...rest
+} = Astro.props;
+
+// Astro stringifies booleans on custom elements (`required="false"`), and any
+// present attribute counts as on — so omit false flags entirely.
+const flag = (on: boolean | undefined) => (on ? '' : undefined);
+
+const state = normalizeStateCode(defaultState);
+if (defaultState && !state) {
+  console.warn(`<SchoolSearch>: ignoring unsupported defaultState "${defaultState}".`);
+}
+---
+
+<edv-school-search
+  {...rest}
+  name={name}
+  required={flag(required)}
+  disabled={flag(disabled)}
+  default-state={state ?? undefined}
+  state-label={stateLabel}
+  school-label={schoolLabel}
+  placeholder={placeholder}
+  hint={hint}
+  limit={limit}
+  endpoint={endpoint}
+  no-recommend={flag(!recommend)}
+  recommend-endpoint={recommendEndpoint}
+  value={value}
+  value-name={valueName}
+></edv-school-search>
+
+<script>
+  import './school-search-element';
+</script>
+
+<style is:global>
+  edv-school-search:not(:defined) {
+    display: block;
+    min-height: 9.5rem;
+  }
+</style>

package/src/components/SchoolSearch/api.ts

@@ -0,0 +1,156 @@
+import type { SchoolRecommendationResponse, SchoolSearchResponse } from './types';
+
+export const DEFAULT_SEARCH_ENDPOINT = 'https://api.edvizion.com/schools/search';
+export const DEFAULT_RECOMMEND_ENDPOINT = 'https://api.edvizion.com/schools/recommendations';
+/** The value a form receives when the user recommended a missing school. */
+export const RECOMMENDED_SCHOOL_ID = 'sch_00000000-0000-0000-0000-000000000000';
+export const MAX_QUERY_LENGTH = 200;
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 100;
+export const MAX_OFFSET = 1000;
+
+/**
+ * Mirrors the API's own tokenizer (anything that is not a letter, digit,
+ * apostrophe or ampersand splits terms) so obviously-invalid queries are
+ * caught before a round trip. The API remains the authority.
+ */
+export function validateQuery(raw: string): string | null {
+  const query = raw.trim();
+  if (!query) return 'Enter a school name or city to search.';
+  if (query.length > MAX_QUERY_LENGTH) return `Search must be ${MAX_QUERY_LENGTH} characters or fewer.`;
+  const terms = query.split(/[^\p{L}\p{N}'&]+/u).filter(Boolean);
+  if (terms.length === 0) return 'Enter letters or numbers to search.';
+  if (!terms.some((term) => term.length >= 2)) return 'Enter at least 2 characters to search.';
+  return null;
+}
+
+export class SchoolSearchError extends Error {
+  constructor(
+    message: string,
+    readonly status: number | null,
+    readonly code: string | null,
+    readonly requestId: string | null,
+  ) {
+    super(message);
+    this.name = 'SchoolSearchError';
+  }
+}
+
+export interface SearchSchoolsOptions {
+  query: string;
+  state: string;
+  limit?: number;
+  offset?: number;
+  endpoint?: string;
+  signal?: AbortSignal;
+}
+
+/** Calls the school search API. */
+export async function searchSchools({
+  query,
+  state,
+  limit = DEFAULT_LIMIT,
+  offset = 0,
+  endpoint = DEFAULT_SEARCH_ENDPOINT,
+  signal,
+}: SearchSchoolsOptions): Promise<SchoolSearchResponse> {
+  const url = new URL(endpoint, globalThis.location?.href);
+  url.searchParams.set('q', query.trim());
+  url.searchParams.set('state', state);
+  url.searchParams.set('limit', String(limit));
+  if (offset > 0) url.searchParams.set('offset', String(offset));
+
+  const { response, body } = await send(url, { method: 'GET', signal }, 'search');
+  if (!body || !Array.isArray((body as SchoolSearchResponse).results)) {
+    throw new SchoolSearchError(unavailable.search, response.status, null, response.headers.get('x-request-id'));
+  }
+  return body as SchoolSearchResponse;
+}
+
+export interface RecommendSchoolOptions {
+  name: string;
+  state: string;
+  notes?: string;
+  endpoint?: string;
+  signal?: AbortSignal;
+}
+
+/**
+ * Reports a school missing from the directory. It is posted to a Google Space
+ * for a person to review — it never enters the directory or search results.
+ * Success is 202. A 502 means the recommendation reached nobody and must be
+ * retried. The recommender is taken from the injected token, not the body.
+ */
+export async function recommendSchool({
+  name,
+  state,
+  notes,
+  endpoint = DEFAULT_RECOMMEND_ENDPOINT,
+  signal,
+}: RecommendSchoolOptions): Promise<SchoolRecommendationResponse> {
+  const payload: Record<string, string> = { name: name.trim(), state };
+  if (notes?.trim()) payload.notes = notes.trim();
+
+  const { body } = await send(
+    new URL(endpoint, globalThis.location?.href),
+    { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload), signal },
+    'recommend',
+  );
+  return body as SchoolRecommendationResponse;
+}
+
+type Operation = 'search' | 'recommend';
+
+const unavailable: Record<Operation, string> = {
+  search: 'School search is unavailable right now. Please try again in a moment.',
+  recommend: 'Your recommendation could not be sent, so it was not received. Please try again.',
+};
+
+/**
+ * Sends a request. No Authorization header is set here: Edvizion Auth
+ * injects the bearer token into outgoing requests.
+ */
+async function send(url: URL, init: RequestInit, operation: Operation) {
+  let response: Response;
+  try {
+    response = await fetch(url, { ...init, headers: { accept: 'application/json', ...init.headers } });
+  } catch (error) {
+    if ((error as Error)?.name === 'AbortError') throw error;
+    throw new SchoolSearchError(unavailable[operation], null, null, null);
+  }
+
+  const requestId = response.headers.get('x-request-id');
+  const body: unknown = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    const { code, message } = readError(body);
+    throw new SchoolSearchError(messageFor(operation, response.status, message), response.status, code, requestId);
+  }
+  return { response, body };
+}
+
+function messageFor(operation: Operation, status: number, serverMessage: string | null): string {
+  if (status === 400) {
+    return serverMessage ?? (operation === 'search' ? 'That search could not be run. Try different words.' : 'Check the school name and try again.');
+  }
+  if (status === 401 || status === 403) {
+    return operation === 'search'
+      ? 'You need to be signed in to search for schools. Sign in and try again.'
+      : 'You need to be signed in to recommend a school. Sign in and try again.';
+  }
+  if (operation === 'recommend' && status === 500) {
+    return 'Recommending schools is unavailable right now. Please try again later.';
+  }
+  return unavailable[operation];
+}
+
+// The API's error envelope is `{ error: { code, message } }`; tolerate a flat one too.
+function readError(body: unknown): { code: string | null; message: string | null } {
+  const source = (body as { error?: unknown })?.error ?? body;
+  if (!source || typeof source !== 'object') return { code: null, message: null };
+  const { code, message } = source as { code?: unknown; message?: unknown };
+  return {
+    code: typeof code === 'string' ? code : null,
+    message: typeof message === 'string' ? message : null,
+  };
+}