npm - @llm4ts/shell - Versions diffs - 0.17.0 → 0.18.1 - Mend

@llm4ts/shell 0.17.0 → 0.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (269) hide show

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/app/cards/page.tsx ADDED Viewed

@@ -0,0 +1,62 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { Card, DataTable, PageLayout } from '@/components';
+import type { DataTableColumn } from '@/components';
+import { useAuth } from '@/auth/AuthProvider';
+import { getCardsPort } from '@/services/registry';
+import type { CardSummary, Money } from '@/services/cards/port';
+const formatMoney = ({ amount, currency }: Money): string =>
+  new Intl.NumberFormat('en-IE', { style: 'currency', currency }).format(
+    amount,
+  );
+const COLUMNS: ReadonlyArray<DataTableColumn<CardSummary>> = [
+  { id: 'label', header: 'Card', cell: (card) => card.label },
+  { id: 'maskedPan', header: 'Number', cell: (card) => card.maskedPan },
+  { id: 'kind', header: 'Type', cell: (card) => card.kind },
+  { id: 'status', header: 'Status', cell: (card) => card.status },
+  { id: 'balance', header: 'Balance', cell: (card) => formatMoney(card.balance) },
+];
+/**
+ * Exemplar list page: loads rows through a port from the registry and renders
+ * them with DataTable inside a Card. No fetch calls, no ad-hoc tables.
+ */
+export default function CardsPage() {
+  const user = useAuth();
+  const [cards, setCards] = useState<ReadonlyArray<CardSummary> | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    void getCardsPort()
+      .listCards(user.customerId)
+      .then((loaded) => {
+        if (!cancelled) {
+          setCards(loaded);
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [user.customerId]);
+  return (
+    <PageLayout title="Your cards" subtitle="Payment cards on your account.">
+      <Card>
+        {cards === null ? (
+          <p className="db-loading">Loading your cards…</p>
+        ) : (
+          <DataTable
+            caption={`Cards for ${user.name}`}
+            columns={COLUMNS}
+            rows={cards}
+            rowKey={(card) => card.id}
+            emptyMessage="You have no cards yet."
+          />
+        )}
+      </Card>
+    </PageLayout>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/app/layout.tsx ADDED Viewed

@@ -0,0 +1,41 @@
+import Link from 'next/link';
+import type { Metadata } from 'next';
+import type { ReactNode } from 'react';
+import { AuthProvider } from '@/auth/AuthProvider';
+import { SignedInBadge } from './signed-in-badge';
+import '@/theme/tokens.css';
+import '@/theme/components.css';
+export const metadata: Metadata = {
+  title: 'DemoBank',
+  description: 'DemoBank online banking (synthetic fixture)',
+};
+/**
+ * App shell: brand, primary navigation, signed-in user. The layout stays a
+ * server component; everything interactive lives in client components.
+ */
+export default function RootLayout({
+  children,
+}: {
+  readonly children: ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <AuthProvider>
+          <header className="db-shell-header">
+            <span className="db-shell-brand">DemoBank</span>
+            <nav className="db-shell-nav" aria-label="Primary">
+              <Link href="/">Home</Link>
+              <Link href="/cards">Cards</Link>
+              <Link href="/profile">Profile</Link>
+            </nav>
+            <SignedInBadge />
+          </header>
+          {children}
+        </AuthProvider>
+      </body>
+    </html>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/app/page.tsx ADDED Viewed

@@ -0,0 +1,26 @@
+'use client';
+import { Card, PageLayout, Stepper } from '@/components';
+import { useAuth } from '@/auth/AuthProvider';
+/** Landing page: greets the stubbed SSO user and shows the house Stepper. */
+export default function HomePage() {
+  const user = useAuth();
+  return (
+    <PageLayout
+      title={`Welcome back, ${user.name}`}
+      subtitle="Your everyday banking, in one place."
+    >
+      <Card title="Getting started">
+        <Stepper
+          steps={['Review your cards', 'Check your profile', 'Explore']}
+          activeIndex={0}
+        />
+        <p>
+          Use the navigation above to review your payment cards or update your
+          contact details.
+        </p>
+      </Card>
+    </PageLayout>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/app/profile/page.tsx ADDED Viewed

@@ -0,0 +1,134 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { Button, Card, Field, Form, PageLayout } from '@/components';
+import type { ValidationErrors } from '@/components';
+import { useAuth } from '@/auth/AuthProvider';
+import { getProfilePort } from '@/services/registry';
+import type { Profile, ProfileUpdate } from '@/services/profile/port';
+type ProfileFormValues = ProfileUpdate;
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const validateProfile = (
+  values: ProfileFormValues,
+): ValidationErrors<ProfileFormValues> => {
+  const errors: {
+    fullName?: string;
+    email?: string;
+    phone?: string;
+  } = {};
+  if (values.fullName.trim().length === 0) {
+    errors.fullName = 'Full name is required.';
+  }
+  if (values.email.trim().length === 0) {
+    errors.email = 'Email is required.';
+  } else if (!EMAIL_PATTERN.test(values.email)) {
+    errors.email = 'Enter a valid email address.';
+  }
+  if (values.phone.trim().length === 0) {
+    errors.phone = 'Phone number is required.';
+  }
+  return errors;
+};
+/**
+ * Exemplar form page: loads via ProfilePort, edits with Form + Field, saves
+ * through the port. Validation lives in a pure function next to the page.
+ */
+export default function ProfilePage() {
+  const user = useAuth();
+  const [profile, setProfile] = useState<Profile | null>(null);
+  const [saved, setSaved] = useState(false);
+  useEffect(() => {
+    let cancelled = false;
+    void getProfilePort()
+      .getProfile(user.customerId)
+      .then((loaded) => {
+        if (!cancelled) {
+          setProfile(loaded);
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [user.customerId]);
+  const handleSubmit = async (values: ProfileFormValues): Promise<void> => {
+    setSaved(false);
+    const updated = await getProfilePort().updateProfile(
+      user.customerId,
+      values,
+    );
+    setProfile(updated);
+    setSaved(true);
+  };
+  return (
+    <PageLayout title="Your profile" subtitle="Contact details we hold for you.">
+      <Card title="Contact details">
+        {profile === null ? (
+          <p className="db-loading">Loading your profile…</p>
+        ) : (
+          <Form<ProfileFormValues>
+            initialValues={{
+              fullName: profile.fullName,
+              email: profile.email,
+              phone: profile.phone,
+            }}
+            validate={validateProfile}
+            onSubmit={handleSubmit}
+          >
+            {({ values, errors, setValue, submitting }) => (
+              <>
+                <Field id="fullName" label="Full name" error={errors.fullName}>
+                  <input
+                    id="fullName"
+                    name="fullName"
+                    value={values.fullName}
+                    onChange={(event) =>
+                      setValue('fullName', event.target.value)
+                    }
+                  />
+                </Field>
+                <Field id="email" label="Email" error={errors.email}>
+                  <input
+                    id="email"
+                    name="email"
+                    type="email"
+                    value={values.email}
+                    onChange={(event) => setValue('email', event.target.value)}
+                  />
+                </Field>
+                <Field id="phone" label="Phone" error={errors.phone}>
+                  <input
+                    id="phone"
+                    name="phone"
+                    type="tel"
+                    value={values.phone}
+                    onChange={(event) => setValue('phone', event.target.value)}
+                  />
+                </Field>
+                <div className="db-form-actions">
+                  <Button type="submit" disabled={submitting}>
+                    {submitting ? 'Saving…' : 'Save changes'}
+                  </Button>
+                </div>
+                {saved ? (
+                  <p
+                    className="db-form-status db-form-status--success"
+                    role="status"
+                  >
+                    Profile saved.
+                  </p>
+                ) : null}
+              </>
+            )}
+          </Form>
+        )}
+      </Card>
+    </PageLayout>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/app/signed-in-badge.tsx ADDED Viewed

@@ -0,0 +1,9 @@
+'use client';
+import { useAuth } from '@/auth/AuthProvider';
+/** Shows who is signed in (via the SSO stub) in the app shell header. */
+export function SignedInBadge() {
+  const user = useAuth();
+  return <span className="db-shell-user">Signed in as {user.name}</span>;
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/auth/AuthProvider.tsx ADDED Viewed

@@ -0,0 +1,36 @@
+'use client';
+import { createContext, useContext } from 'react';
+import type { ReactNode } from 'react';
+export interface AuthUser {
+  readonly name: string;
+  readonly customerId: string;
+}
+/**
+ * SSO stub. In production the shell exchanges the gateway session for a
+ * profile; here a fixed user is always signed in. Pages consume useAuth()
+ * and NEVER implement login, token handling, or redirects themselves.
+ */
+const DEMO_USER: AuthUser = {
+  name: 'Ada Doe',
+  customerId: 'CUST-1001',
+};
+const AuthContext = createContext<AuthUser | null>(null);
+export function AuthProvider({ children }: { readonly children: ReactNode }) {
+  return (
+    <AuthContext.Provider value={DEMO_USER}>{children}</AuthContext.Provider>
+  );
+}
+/** Current signed-in user. Throws when rendered outside the app shell. */
+export function useAuth(): AuthUser {
+  const user = useContext(AuthContext);
+  if (user === null) {
+    throw new Error('useAuth must be used inside <AuthProvider>');
+  }
+  return user;
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/components/Button.tsx ADDED Viewed

@@ -0,0 +1,27 @@
+'use client';
+import type { ButtonHTMLAttributes } from 'react';
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost';
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  readonly variant?: ButtonVariant;
+}
+/** House button. Default type is "button"; forms opt in with type="submit". */
+export function Button({
+  variant = 'primary',
+  type = 'button',
+  className,
+  children,
+  ...rest
+}: ButtonProps) {
+  const classes = ['db-button', `db-button--${variant}`, className]
+    .filter((c) => typeof c === 'string' && c.length > 0)
+    .join(' ');
+  return (
+    <button type={type} className={classes} {...rest}>
+      {children}
+    </button>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/components/Card.tsx ADDED Viewed

@@ -0,0 +1,18 @@
+'use client';
+import type { ReactNode } from 'react';
+export interface CardProps {
+  readonly title?: string;
+  readonly children: ReactNode;
+}
+/** House surface. Every block of page content sits inside a Card. */
+export function Card({ title, children }: CardProps) {
+  return (
+    <section className="db-card">
+      {title !== undefined ? <h2 className="db-card-title">{title}</h2> : null}
+      {children}
+    </section>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/components/DataTable.tsx ADDED Viewed

@@ -0,0 +1,57 @@
+'use client';
+import type { ReactNode } from 'react';
+export interface DataTableColumn<Row> {
+  /** Stable column id, used as the React key for header and cells. */
+  readonly id: string;
+  readonly header: string;
+  readonly cell: (row: Row) => ReactNode;
+}
+export interface DataTableProps<Row> {
+  readonly caption: string;
+  readonly columns: ReadonlyArray<DataTableColumn<Row>>;
+  readonly rows: ReadonlyArray<Row>;
+  readonly rowKey: (row: Row) => string;
+  readonly emptyMessage?: string;
+}
+/**
+ * House table for read-only listings. Rendering stays declarative: pages
+ * describe columns, never map over rows in JSX themselves.
+ */
+export function DataTable<Row>({
+  caption,
+  columns,
+  rows,
+  rowKey,
+  emptyMessage = 'Nothing to show yet.',
+}: DataTableProps<Row>) {
+  if (rows.length === 0) {
+    return <p className="db-table-empty">{emptyMessage}</p>;
+  }
+  return (
+    <table className="db-table">
+      <caption>{caption}</caption>
+      <thead>
+        <tr>
+          {columns.map((column) => (
+            <th key={column.id} scope="col">
+              {column.header}
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((row) => (
+          <tr key={rowKey(row)}>
+            {columns.map((column) => (
+              <td key={column.id}>{column.cell(row)}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/components/Field.tsx ADDED Viewed

@@ -0,0 +1,34 @@
+'use client';
+import type { ReactNode } from 'react';
+export interface FieldProps {
+  /** id of the control rendered inside the field (label htmlFor pairs with it). */
+  readonly id: string;
+  readonly label: string;
+  /** Validation message; when set the field renders in its invalid state. */
+  readonly error?: string;
+  /** Exactly one form control (input/select/textarea) with the matching id. */
+  readonly children: ReactNode;
+}
+/**
+ * Field wraps label + control + error. Pages never hand-roll label/error
+ * markup; every form control lives inside a Field.
+ */
+export function Field({ id, label, error, children }: FieldProps) {
+  const invalid = typeof error === 'string' && error.length > 0;
+  return (
+    <div className={invalid ? 'db-field db-field--invalid' : 'db-field'}>
+      <label className="db-field-label" htmlFor={id}>
+        {label}
+      </label>
+      {children}
+      {invalid ? (
+        <p className="db-field-error" role="alert" id={`${id}-error`}>
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/components/Form.tsx ADDED Viewed

@@ -0,0 +1,70 @@
+'use client';
+import { useCallback, useState } from 'react';
+import type { FormEvent, ReactNode } from 'react';
+/** Validation map: field name -> message. Empty map means valid. */
+export type ValidationErrors<T> = Partial<
+  Record<Extract<keyof T, string>, string>
+>;
+export interface FormRenderProps<T extends object> {
+  readonly values: T;
+  readonly errors: ValidationErrors<T>;
+  readonly setValue: <K extends keyof T>(key: K, value: T[K]) => void;
+  readonly submitting: boolean;
+}
+export interface FormProps<T extends object> {
+  readonly initialValues: T;
+  /** Pure, synchronous. Returns a map of messages; empty map = submit. */
+  readonly validate?: (values: T) => ValidationErrors<T>;
+  readonly onSubmit: (values: T) => void | Promise<void>;
+  readonly children: (form: FormRenderProps<T>) => ReactNode;
+}
+/**
+ * House form. Owns values, validation, and submit; pages provide fields via
+ * the render prop and never call preventDefault or track error state
+ * themselves.
+ */
+export function Form<T extends object>({
+  initialValues,
+  validate,
+  onSubmit,
+  children,
+}: FormProps<T>) {
+  const [values, setValues] = useState<T>(initialValues);
+  const [errors, setErrors] = useState<ValidationErrors<T>>({});
+  const [submitting, setSubmitting] = useState(false);
+  const setValue = useCallback(<K extends keyof T>(key: K, value: T[K]) => {
+    setValues((prev) => {
+      const next = { ...prev };
+      next[key] = value;
+      return next;
+    });
+  }, []);
+  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const nextErrors = validate === undefined ? {} : validate(values);
+    setErrors(nextErrors);
+    if (Object.keys(nextErrors).length > 0) {
+      return;
+    }
+    const result = onSubmit(values);
+    if (result instanceof Promise) {
+      setSubmitting(true);
+      void result.finally(() => {
+        setSubmitting(false);
+      });
+    }
+  };
+  return (
+    <form onSubmit={handleSubmit} noValidate>
+      {children({ values, errors, setValue, submitting })}
+    </form>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/components/PageLayout.tsx ADDED Viewed

@@ -0,0 +1,39 @@
+'use client';
+import type { ReactNode } from 'react';
+export interface PageLayoutProps {
+  readonly title: string;
+  readonly subtitle?: string;
+  /** Page-level actions (Buttons), rendered top-right of the header. */
+  readonly actions?: ReactNode;
+  readonly children: ReactNode;
+}
+/**
+ * House page frame: heading, optional subtitle and actions, then content.
+ * Every page renders exactly one PageLayout at its root.
+ */
+export function PageLayout({
+  title,
+  subtitle,
+  actions,
+  children,
+}: PageLayoutProps) {
+  return (
+    <main className="db-page">
+      <header className="db-page-header">
+        <div>
+          <h1 className="db-page-title">{title}</h1>
+          {subtitle !== undefined ? (
+            <p className="db-page-subtitle">{subtitle}</p>
+          ) : null}
+        </div>
+        {actions !== undefined ? (
+          <div className="db-page-actions">{actions}</div>
+        ) : null}
+      </header>
+      {children}
+    </main>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/components/Stepper.tsx ADDED Viewed

@@ -0,0 +1,29 @@
+'use client';
+export interface StepperProps {
+  readonly steps: ReadonlyArray<string>;
+  /** Zero-based index of the active step. */
+  readonly activeIndex: number;
+}
+/** House progress indicator for multi-step journeys (wizards, onboarding). */
+export function Stepper({ steps, activeIndex }: StepperProps) {
+  return (
+    <ol className="db-stepper">
+      {steps.map((step, index) => (
+        <li
+          key={step}
+          className={
+            index === activeIndex
+              ? 'db-stepper-step db-stepper-step--active'
+              : 'db-stepper-step'
+          }
+          aria-current={index === activeIndex ? 'step' : undefined}
+        >
+          <span className="db-stepper-index">{index + 1}</span>
+          {step}
+        </li>
+      ))}
+    </ol>
+  );
+}

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/components/index.ts ADDED Viewed

@@ -0,0 +1,19 @@
+// Design-system barrel: pages import components from '@/components'.
+export { Button } from './Button';
+export type { ButtonProps, ButtonVariant } from './Button';
+export { Card } from './Card';
+export type { CardProps } from './Card';
+export { DataTable } from './DataTable';
+export type { DataTableColumn, DataTableProps } from './DataTable';
+export { Field } from './Field';
+export type { FieldProps } from './Field';
+export { Form } from './Form';
+export type {
+  FormProps,
+  FormRenderProps,
+  ValidationErrors,
+} from './Form';
+export { PageLayout } from './PageLayout';
+export type { PageLayoutProps } from './PageLayout';
+export { Stepper } from './Stepper';
+export type { StepperProps } from './Stepper';

package/kits/j2ee-nextjs/fixtures/demo-bank/nextjs/src/services/cards/mock.ts ADDED Viewed

@@ -0,0 +1,47 @@
+// Mock adapter for CardsPort: deterministic fixture data plus a small
+// artificial delay so pages exercise their loading states.
+import type { CardsPort, CardsPortFactory, CardSummary } from './port';
+const DELAY_MS = 20;
+const delay = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+const FIXTURE_CARDS: ReadonlyArray<CardSummary> = [
+  {
+    id: 'card-001',
+    label: 'Everyday Debit',
+    maskedPan: '**** **** **** 4242',
+    kind: 'debit',
+    status: 'active',
+    balance: { amount: 1245.5, currency: 'EUR' },
+  },
+  {
+    id: 'card-002',
+    label: 'Travel Credit',
+    maskedPan: '**** **** **** 9310',
+    kind: 'credit',
+    status: 'active',
+    balance: { amount: -320.75, currency: 'EUR' },
+  },
+  {
+    id: 'card-003',
+    label: 'Backup Debit',
+    maskedPan: '**** **** **** 0007',
+    kind: 'debit',
+    status: 'blocked',
+    balance: { amount: 0, currency: 'EUR' },
+  },
+];
+export const makeMockCardsPort: CardsPortFactory = () => {
+  const port: CardsPort = {
+    async listCards(customerId) {
+      await delay(DELAY_MS);
+      // The fixture gateway knows a single customer; anyone else has no cards.
+      return customerId === 'CUST-1001' ? FIXTURE_CARDS : [];
+    },
+  };
+  return port;
+};