@edvizion/astro-components 0.1.0

package/src/components/SchoolSearch/types.ts

@@ -0,0 +1,64 @@
+/** One hit from `GET /schools/search`. Address schools by `edvizionId`. */
+export interface SchoolSearchResult {
+  edvizionId: string;
+  slug: string;
+  name: string;
+  /** Always null today — no districts have been imported yet. */
+  districtEdvizionId: string | null;
+  city: string | null;
+  state: string;
+  type: string | null;
+  gradeSpan: { low: string | null; high: string | null } | null;
+  website: string | null;
+}
+
+export interface SchoolSearchResponse {
+  requestId: string;
+  query: string;
+  state: string | null;
+  count: number;
+  /** Ordered best match first. */
+  results: SchoolSearchResult[];
+}
+
+/** The minimum a selection needs; a prefilled value may only have these. */
+export interface SelectedSchool {
+  /** `"sch_00000000-0000-0000-0000-000000000000"` when the user recommended a missing school. */
+  edvizionId: string;
+  name: string;
+  city?: string | null;
+  state?: string | null;
+  /** Present when the user recommended this school rather than choosing one. */
+  recommendation?: SchoolRecommendation;
+}
+
+/** `POST /schools/recommendations` — 202 Accepted. */
+export interface SchoolRecommendationResponse {
+  requestId: string;
+  status: 'received_for_review';
+  name: string;
+  state: string;
+  submittedAt: string;
+}
+
+export interface SchoolRecommendation {
+  name: string;
+  state: string;
+  notes: string | null;
+  requestId: string | null;
+  submittedAt: string | null;
+}
+
+export interface SchoolSearchEventDetail {
+  query: string;
+  state: string;
+  offset: number;
+  results: SchoolSearchResult[];
+}
+
+export interface SchoolSearchErrorDetail {
+  status: number | null;
+  code: string | null;
+  requestId: string | null;
+  message: string;
+}

package/src/components/SchoolSearch/us-states.ts

@@ -0,0 +1,63 @@
+/** The 50 states plus DC, as USPS codes. The search API is US-only for now. */
+export const US_STATES = [
+  { code: 'AL', name: 'Alabama' },
+  { code: 'AK', name: 'Alaska' },
+  { code: 'AZ', name: 'Arizona' },
+  { code: 'AR', name: 'Arkansas' },
+  { code: 'CA', name: 'California' },
+  { code: 'CO', name: 'Colorado' },
+  { code: 'CT', name: 'Connecticut' },
+  { code: 'DE', name: 'Delaware' },
+  { code: 'DC', name: 'District of Columbia' },
+  { code: 'FL', name: 'Florida' },
+  { code: 'GA', name: 'Georgia' },
+  { code: 'HI', name: 'Hawaii' },
+  { code: 'ID', name: 'Idaho' },
+  { code: 'IL', name: 'Illinois' },
+  { code: 'IN', name: 'Indiana' },
+  { code: 'IA', name: 'Iowa' },
+  { code: 'KS', name: 'Kansas' },
+  { code: 'KY', name: 'Kentucky' },
+  { code: 'LA', name: 'Louisiana' },
+  { code: 'ME', name: 'Maine' },
+  { code: 'MD', name: 'Maryland' },
+  { code: 'MA', name: 'Massachusetts' },
+  { code: 'MI', name: 'Michigan' },
+  { code: 'MN', name: 'Minnesota' },
+  { code: 'MS', name: 'Mississippi' },
+  { code: 'MO', name: 'Missouri' },
+  { code: 'MT', name: 'Montana' },
+  { code: 'NE', name: 'Nebraska' },
+  { code: 'NV', name: 'Nevada' },
+  { code: 'NH', name: 'New Hampshire' },
+  { code: 'NJ', name: 'New Jersey' },
+  { code: 'NM', name: 'New Mexico' },
+  { code: 'NY', name: 'New York' },
+  { code: 'NC', name: 'North Carolina' },
+  { code: 'ND', name: 'North Dakota' },
+  { code: 'OH', name: 'Ohio' },
+  { code: 'OK', name: 'Oklahoma' },
+  { code: 'OR', name: 'Oregon' },
+  { code: 'PA', name: 'Pennsylvania' },
+  { code: 'RI', name: 'Rhode Island' },
+  { code: 'SC', name: 'South Carolina' },
+  { code: 'SD', name: 'South Dakota' },
+  { code: 'TN', name: 'Tennessee' },
+  { code: 'TX', name: 'Texas' },
+  { code: 'UT', name: 'Utah' },
+  { code: 'VT', name: 'Vermont' },
+  { code: 'VA', name: 'Virginia' },
+  { code: 'WA', name: 'Washington' },
+  { code: 'WV', name: 'West Virginia' },
+  { code: 'WI', name: 'Wisconsin' },
+  { code: 'WY', name: 'Wyoming' },
+] as const;
+
+export type UsStateCode = (typeof US_STATES)[number]['code'];
+
+/** Returns the upper-cased code if it is a supported state, otherwise null. */
+export function normalizeStateCode(value: string | null | undefined): UsStateCode | null {
+  if (!value) return null;
+  const code = value.trim().toUpperCase();
+  return US_STATES.some((s) => s.code === code) ? (code as UsStateCode) : null;
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export { default as SchoolSearch } from './components/SchoolSearch/SchoolSearch.astro';
+export { default as EdvizionTheme } from './theme/EdvizionTheme.astro';
+
+export {
+  DEFAULT_RECOMMEND_ENDPOINT,
+  DEFAULT_SEARCH_ENDPOINT,
+  RECOMMENDED_SCHOOL_ID,
+  recommendSchool,
+  SchoolSearchError,
+  searchSchools,
+  validateQuery,
+  type RecommendSchoolOptions,
+  type SearchSchoolsOptions,
+} from './components/SchoolSearch/api';
+export type { EdvSchoolSearchElement } from './components/SchoolSearch/school-search-element';
+export type {
+  SchoolRecommendation,
+  SchoolRecommendationResponse,
+  SchoolSearchErrorDetail,
+  SchoolSearchEventDetail,
+  SchoolSearchResponse,
+  SchoolSearchResult,
+  SelectedSchool,
+} from './components/SchoolSearch/types';
+export { US_STATES, normalizeStateCode, type UsStateCode } from './components/SchoolSearch/us-states';
+
+export {
+  DEFAULT_TOKENS,
+  TOKEN_PROPERTIES,
+  cssVar,
+  tokenDeclarations,
+  type ThemeToken,
+  type ThemeTokens,
+} from './theme/tokens';
+export { baseComponentStyles } from './theme/component-styles';

package/src/theme/EdvizionTheme.astro

@@ -0,0 +1,32 @@
+---
+/**
+ * Applies Edvizion design tokens to everything it wraps (or to the whole page
+ * with `global`). Every Edvizion component reads these tokens, including
+ * inside shadow DOM, so one theme restyles all of them.
+ */
+import { DEFAULT_TOKENS, tokenDeclarations, type ThemeTokens } from './tokens';
+
+interface Props {
+  /** Token overrides, merged over the Edvizion defaults. */
+  theme?: Partial<ThemeTokens>;
+  /** Apply to `:root` instead of wrapping the slot. */
+  global?: boolean;
+}
+
+const { theme = {}, global = false } = Astro.props;
+
+const scopeId = `edv-${Math.random().toString(36).slice(2, 10)}`;
+const selector = global ? ':root' : `[data-edv-theme="${scopeId}"]`;
+const css = `${selector} { ${tokenDeclarations({ ...DEFAULT_TOKENS, ...theme })} }`;
+---
+
+<style set:html={css}></style>
+{
+  global ? (
+    <slot />
+  ) : (
+    <div data-edv-theme={scopeId} style="display: contents">
+      <slot />
+    </div>
+  )
+}

package/src/theme/component-styles.ts

@@ -0,0 +1,70 @@
+import { cssVar } from './tokens';
+
+/**
+ * Base styles every Edvizion component's shadow root starts from, so
+ * typography, controls and focus treatment look the same across components.
+ */
+export const baseComponentStyles = /* css */ `
+  :host {
+    display: block;
+    font-family: ${cssVar('fontFamily')};
+    font-size: ${cssVar('fontSize')};
+    line-height: ${cssVar('lineHeight')};
+    color: ${cssVar('colorText')};
+  }
+  :host([hidden]) { display: none; }
+  *, *::before, *::after { box-sizing: border-box; }
+
+  .edv-label {
+    display: block;
+    font-weight: ${cssVar('fontWeightStrong')};
+    margin-block-end: calc(${cssVar('space')} * 0.5);
+  }
+  .edv-required { color: ${cssVar('colorDanger')}; margin-inline-start: 0.125em; }
+  .edv-hint { margin: calc(${cssVar('space')} * 0.5) 0 0; font-size: ${cssVar('fontSizeSmall')}; color: ${cssVar('colorTextMuted')}; }
+  .edv-error { margin: calc(${cssVar('space')} * 0.5) 0 0; font-size: ${cssVar('fontSizeSmall')}; color: ${cssVar('colorDanger')}; font-weight: ${cssVar('fontWeightStrong')}; }
+
+  .edv-control {
+    font: inherit;
+    color: inherit;
+    width: 100%;
+    min-height: ${cssVar('controlHeight')};
+    padding: 0 calc(${cssVar('space')} * 1.5);
+    background: ${cssVar('colorSurface')};
+    border: 1px solid ${cssVar('colorBorderStrong')};
+    border-radius: ${cssVar('radiusSmall')};
+  }
+  .edv-control:disabled { background: ${cssVar('colorSurfaceMuted')}; color: ${cssVar('colorTextMuted')}; cursor: not-allowed; }
+  .edv-control[aria-invalid='true'] { border-color: ${cssVar('colorDanger')}; }
+
+  .edv-button {
+    font: inherit;
+    font-weight: ${cssVar('fontWeightStrong')};
+    min-height: ${cssVar('controlHeight')};
+    padding: 0 calc(${cssVar('space')} * 2);
+    border-radius: ${cssVar('radiusSmall')};
+    border: 1px solid ${cssVar('colorPrimary')};
+    background: ${cssVar('colorPrimary')};
+    color: ${cssVar('colorOnPrimary')};
+    cursor: pointer;
+    white-space: nowrap;
+  }
+  .edv-button:hover:not(:disabled) { background: ${cssVar('colorPrimaryHover')}; border-color: ${cssVar('colorPrimaryHover')}; }
+  .edv-button:disabled { opacity: 0.55; cursor: not-allowed; }
+  .edv-button--secondary { background: transparent; color: ${cssVar('colorPrimary')}; }
+  .edv-button--secondary:hover:not(:disabled) { background: ${cssVar('colorHighlight')}; }
+
+  :focus-visible {
+    outline: ${cssVar('focusRingWidth')} solid ${cssVar('colorFocusRing')};
+    outline-offset: 2px;
+  }
+
+  .edv-visually-hidden {
+    position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px;
+    overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    * { transition: none !important; animation: none !important; }
+  }
+`;

package/src/theme/tokens.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared design tokens for every Edvizion Astro component.
+ *
+ * Each token is a CSS custom property. Components read them with a built-in
+ * fallback (see `cssVar`), so they render correctly with no theme at all, and
+ * `<EdvizionTheme>` (or any stylesheet) overrides them by setting the property.
+ * Custom properties inherit through shadow roots, which is what lets one theme
+ * reach into every component's shadow DOM.
+ */
+export const TOKEN_PROPERTIES = {
+  fontFamily: '--edv-font-family',
+  fontSize: '--edv-font-size',
+  fontSizeSmall: '--edv-font-size-small',
+  fontWeightStrong: '--edv-font-weight-strong',
+  lineHeight: '--edv-line-height',
+
+  colorText: '--edv-color-text',
+  colorTextMuted: '--edv-color-text-muted',
+  colorSurface: '--edv-color-surface',
+  colorSurfaceMuted: '--edv-color-surface-muted',
+  colorBorder: '--edv-color-border',
+  colorBorderStrong: '--edv-color-border-strong',
+  colorPrimary: '--edv-color-primary',
+  colorPrimaryHover: '--edv-color-primary-hover',
+  colorOnPrimary: '--edv-color-on-primary',
+  colorHighlight: '--edv-color-highlight',
+  colorDanger: '--edv-color-danger',
+  colorFocusRing: '--edv-color-focus-ring',
+
+  radius: '--edv-radius',
+  radiusSmall: '--edv-radius-small',
+  space: '--edv-space',
+  controlHeight: '--edv-control-height',
+  focusRingWidth: '--edv-focus-ring-width',
+  shadow: '--edv-shadow',
+} as const;
+
+export type ThemeToken = keyof typeof TOKEN_PROPERTIES;
+export type ThemeTokens = Record<ThemeToken, string>;
+
+export const DEFAULT_TOKENS: ThemeTokens = {
+  fontFamily: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+  fontSize: '1rem',
+  fontSizeSmall: '0.875rem',
+  fontWeightStrong: '600',
+  lineHeight: '1.5',
+
+  colorText: '#1f2937',
+  colorTextMuted: '#4b5563',
+  colorSurface: '#ffffff',
+  colorSurfaceMuted: '#f3f4f6',
+  colorBorder: '#d1d5db',
+  colorBorderStrong: '#6b7280',
+  colorPrimary: '#1d4ed8',
+  colorPrimaryHover: '#1e40af',
+  colorOnPrimary: '#ffffff',
+  colorHighlight: '#dbeafe',
+  colorDanger: '#b91c1c',
+  colorFocusRing: '#2563eb',
+
+  radius: '0.5rem',
+  radiusSmall: '0.375rem',
+  space: '0.5rem',
+  controlHeight: '2.5rem',
+  focusRingWidth: '3px',
+  shadow: '0 1px 2px rgb(0 0 0 / 0.06), 0 1px 3px rgb(0 0 0 / 0.1)',
+};
+
+/** `var(--edv-x, <light default>)` — use this in component styles. */
+export function cssVar(token: ThemeToken): string {
+  return `var(${TOKEN_PROPERTIES[token]}, ${DEFAULT_TOKENS[token]})`;
+}
+
+/** Serialises tokens as declarations, e.g. `--edv-radius: 0.5rem;`. */
+export function tokenDeclarations(tokens: Partial<ThemeTokens>): string {
+  return (Object.keys(tokens) as ThemeToken[])
+    .filter((key) => key in TOKEN_PROPERTIES && tokens[key] != null)
+    .map((key) => `${TOKEN_PROPERTIES[key]}: ${sanitizeValue(String(tokens[key]))};`)
+    .join(' ');
+}
+
+// Values are written into a <style> element, so they must not be able to
+// close it or open a new rule.
+function sanitizeValue(value: string): string {
+  return value.replace(/[<>{};]/g, '');
+}