@namostack/cli 0.1.0-rc.1 → 0.1.0-rc.2

package/templates/react/src/App.tsx

@@ -1,10 +1,84 @@
 import { Text } from '@juliensouki/seedui';
+import { styled } from '@juliensouki/seedui/sc';
+import { useEffect, useState } from 'react';
+import { Code, Muted } from './components/styles';
+import { Counter } from './components/Counter';
+import { Notify } from './components/Notify';
+import { describeError } from './errors';
 import { useNamostack } from './useNamostack';
 
+const Page = styled.main((props) => ({
+  maxWidth: 560,
+  margin: '0 auto',
+  padding: '40px 24px',
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 24,
+  [props.theme.breakpoints.down('sm')]: {
+    padding: '24px 16px',
+  },
+}));
+
+const Header = styled.header({
+  display: 'flex',
+  alignItems: 'center',
+  gap: 16,
+});
+
+const Icon = styled.img({
+  width: 56,
+  height: 56,
+  flexShrink: 0,
+});
+
+const Link = styled.a((props) => ({
+  color: props.theme.colors.primary.default,
+  textDecoration: 'none',
+  '&:hover': { textDecoration: 'underline' },
+}));
+
 export function App() {
-  const { context } = useNamostack();
+  const { context, user } = useNamostack();
+  const [displayName, setDisplayName] = useState<string>();
+  const [error, setError] = useState<string>();
+
+  useEffect(() => {
+    user
+      .getProfile()
+      .then((profile) => setDisplayName(profile.displayName))
+      .catch((caught: unknown) =>
+        setError(describeError(caught, 'user:profile:read')),
+      );
+  }, [user]);
 
   return (
-    <Text variant="h3">Welcome to your namostack plugin {context.name}</Text>
+    <Page>
+      <Header>
+        <Icon src={`${import.meta.env.BASE_URL}icon.svg`} alt="" />
+        <div>
+          <Text variant="h3">{context.name}</Text>
+          <Muted variant="p">
+            {displayName ? `Hi ${displayName}, ` : 'Hi, '}
+            this is your new plugin.
+          </Muted>
+          {error && <Muted variant="caption">{error}</Muted>}
+        </div>
+      </Header>
+
+      <Counter />
+      <Notify />
+
+      <Muted variant="caption">
+        Edit <Code>src/App.tsx</Code> and save to see it change, or{' '}
+        <Link
+          href="https://docs.namostack.com"
+          target="_blank"
+          rel="noreferrer"
+        >
+          read the docs
+        </Link>
+        .
+      </Muted>
+    </Page>
   );
 }

package/templates/react/src/NamostackProvider.tsx

@@ -1,8 +1,16 @@
 import { ThemeProvider } from '@juliensouki/seedui';
+import { createGlobalStyle } from '@juliensouki/seedui/sc';
 import type { Namostack } from '@namostack/plugin-sdk';
 import { useEffect, useState, type ReactNode } from 'react';
 import { NamostackContext } from './useNamostack';
 
+// seedui doesn't reset the page; without this, browsers add an 8px margin.
+const GlobalStyle = createGlobalStyle`
+  body {
+    margin: 0;
+  }
+`;
+
 interface NamostackProviderProps {
   namostack: Namostack;
   children: ReactNode;
@@ -26,6 +34,7 @@ export function NamostackProvider({
 
   return (
     <NamostackContext.Provider value={namostack}>
+      <GlobalStyle />
       <ThemeProvider mode={mode}>{children}</ThemeProvider>
     </NamostackContext.Provider>
   );

package/templates/react/src/components/Counter.tsx

@@ -0,0 +1,101 @@
+import { Button, Text } from '@juliensouki/seedui';
+import type { StoredDocument } from '@namostack/plugin-sdk';
+import { useEffect, useState } from 'react';
+import { describeError } from '../errors';
+import { useNamostack } from '../useNamostack';
+import { ExampleCard } from './ExampleCard';
+import { Actions, Code } from './styles';
+
+interface Clicks {
+  count: number;
+}
+
+type Action = 'increment' | 'reset';
+
+/** A counter saved for the current user: it survives reloads and devices. */
+export function Counter() {
+  const { data } = useNamostack();
+  const [clicks, setClicks] = useState<StoredDocument<Clicks> | null>();
+  const [pending, setPending] = useState<Action>();
+  const [error, setError] = useState<string>();
+
+  useEffect(() => {
+    data
+      .find<Clicks>('clicks', { limit: 1 })
+      .then(({ items }) => setClicks(items[0] ?? null))
+      .catch((caught: unknown) => {
+        setClicks(null);
+        setError(describeError(caught, 'storage'));
+      });
+  }, [data]);
+
+  const run = async (
+    action: Action,
+    change: () => Promise<StoredDocument<Clicks> | null>,
+  ) => {
+    setPending(action);
+    setError(undefined);
+
+    try {
+      setClicks(await change());
+    } catch (caught) {
+      setError(describeError(caught, 'storage'));
+    } finally {
+      setPending(undefined);
+    }
+  };
+
+  const increment = () =>
+    run('increment', () =>
+      clicks
+        ? data.update<Clicks>('clicks', clicks.id, { count: clicks.count + 1 })
+        : data.insert<Clicks>('clicks', { count: 1 }),
+    );
+
+  const reset = () =>
+    run('reset', async () => {
+      if (clicks) {
+        await data.delete('clicks', clicks.id);
+      }
+
+      return null;
+    });
+
+  const loading = clicks === undefined;
+
+  return (
+    <ExampleCard
+      title="Save data"
+      permission="storage"
+      error={error}
+      description={
+        <>
+          Each click is saved with <Code>data.update</Code>: reload, the count
+          stays.
+        </>
+      }
+    >
+      <Text variant="h2">{clicks?.count ?? 0}</Text>
+      <Actions>
+        <Button
+          size="md"
+          isLoading={pending === 'increment'}
+          disabled={loading || pending === 'reset'}
+          onClick={increment}
+        >
+          Click me
+        </Button>
+        <Button
+          size="md"
+          color="neutral"
+          variant="transparent"
+          isLoading={pending === 'reset'}
+          disabled={!clicks || pending === 'increment'}
+          onClick={reset}
+        >
+          Reset
+        </Button>
+      </Actions>
+    </ExampleCard>
+  );
+}

package/templates/react/src/components/ExampleCard.tsx

@@ -0,0 +1,55 @@
+import { Card, Tag, Text } from '@juliensouki/seedui';
+import { styled } from '@juliensouki/seedui/sc';
+import type { ReactNode } from 'react';
+import { Muted } from './styles';
+
+const Root = styled(Card)({
+  width: '100%',
+  boxSizing: 'border-box',
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 16,
+});
+
+const Heading = styled.div({
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 8,
+});
+
+const ErrorText = styled(Text)((props) => ({
+  color: props.theme.colors.error.default,
+}));
+
+interface ExampleCardProps {
+  title: string;
+  description: ReactNode;
+  /** The manifest permission the example needs. */
+  permission: string;
+  error?: string;
+  children: ReactNode;
+}
+
+/** One SDK feature: what it does, the permission it needs, and a way to try it. */
+export function ExampleCard({
+  title,
+  description,
+  permission,
+  error,
+  children,
+}: ExampleCardProps) {
+  return (
+    <Root variant="outlined" padding={20}>
+      <Heading>
+        <Text variant="h5">{title}</Text>
+        <Tag color="neutral" size="sm">
+          {permission}
+        </Tag>
+      </Heading>
+      <Muted variant="p">{description}</Muted>
+      {children}
+      {error && <ErrorText variant="caption">{error}</ErrorText>}
+    </Root>
+  );
+}

package/templates/react/src/components/Notify.tsx

@@ -0,0 +1,41 @@
+import { Button } from '@juliensouki/seedui';
+import { useState } from 'react';
+import { describeError } from '../errors';
+import { useNamostack } from '../useNamostack';
+import { ExampleCard } from './ExampleCard';
+import { Actions, Code } from './styles';
+
+/** Shows a toast in the app, outside the plugin's frame. */
+export function Notify() {
+  const { ui } = useNamostack();
+  const [error, setError] = useState<string>();
+
+  const notify = async () => {
+    setError(undefined);
+
+    try {
+      await ui.notify({ message: 'Hello from your plugin!', tone: 'success' });
+    } catch (caught) {
+      setError(describeError(caught, 'ui:notify'));
+    }
+  };
+
+  return (
+    <ExampleCard
+      title="Talk to the app"
+      permission="ui:notify"
+      error={error}
+      description={
+        <>
+          <Code>ui.notify</Code> shows a notification in the app.
+        </>
+      }
+    >
+      <Actions>
+        <Button size="md" color="neutral" onClick={notify}>
+          Say hello
+        </Button>
+      </Actions>
+    </ExampleCard>
+  );
+}

package/templates/react/src/components/styles.ts

@@ -0,0 +1,24 @@
+import { Text } from '@juliensouki/seedui';
+import { styled } from '@juliensouki/seedui/sc';
+
+export const Actions = styled.div({
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: 8,
+});
+
+export const Code = styled.code((props) => ({
+  padding: '1px 6px',
+  borderRadius: props.theme.borderRadius(1),
+  background:
+    props.theme.colors.neutral[props.theme.mode === 'light' ? 200 : 400],
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+  fontSize: '0.875em',
+}));
+
+export const Muted = styled(Text)((props) => ({
+  color:
+    props.theme.mode === 'light'
+      ? props.theme.colors.neutral[600]
+      : props.theme.colors.neutral[900],
+}));

package/templates/react/src/errors.ts

@@ -0,0 +1,10 @@
+import { BridgeError } from '@namostack/plugin-sdk';
+
+/** What to show when an SDK call fails; a missing permission says how to add it. */
+export function describeError(error: unknown, permission: string): string {
+  if (error instanceof BridgeError && error.code === 'permission_denied') {
+    return `Add "${permission}" to the permissions in namostack.plugin.json.`;
+  }
+
+  return error instanceof BridgeError ? error.message : String(error);
+}

package/templates/vanilla/index.html

@@ -6,7 +6,56 @@
     <title>{{name}}</title>
   </head>
   <body>
-    <div id="root"></div>
+    <main class="page" hidden>
+      <header class="header">
+        <img class="icon" src="./icon.svg" alt="" />
+        <div>
+          <h1 class="h3" id="name"></h1>
+          <p class="p muted" id="greeting">Hi, this is your new plugin.</p>
+          <p class="caption muted" id="greeting-error" hidden></p>
+        </div>
+      </header>
+
+      <section class="card">
+        <div class="card-heading">
+          <h2 class="h5">Save data</h2>
+          <span class="tag">storage</span>
+        </div>
+        <p class="p muted">
+          Each click is saved with <code>data.update</code>: reload, the count
+          stays.
+        </p>
+        <p class="h2" id="count">0</p>
+        <div class="actions">
+          <button class="button" id="increment" disabled>Click me</button>
+          <button class="button button-transparent" id="reset" disabled>
+            Reset
+          </button>
+        </div>
+        <p class="caption error" id="count-error" hidden></p>
+      </section>
+
+      <section class="card">
+        <div class="card-heading">
+          <h2 class="h5">Talk to the app</h2>
+          <span class="tag">ui:notify</span>
+        </div>
+        <p class="p muted">
+          <code>ui.notify</code> shows a notification in the app.
+        </p>
+        <div class="actions">
+          <button class="button button-neutral" id="notify">Say hello</button>
+        </div>
+        <p class="caption error" id="notify-error" hidden></p>
+      </section>
+
+      <p class="caption muted">
+        Edit <code>src/main.ts</code> and save to see it change, or
+        <a href="https://docs.namostack.com" target="_blank" rel="noreferrer"
+          >read the docs</a
+        >.
+      </p>
+    </main>
     <script type="module" src="/src/main.ts"></script>
   </body>
 </html>

package/templates/vanilla/package.json

@@ -7,6 +7,8 @@
     "typecheck": "tsc"
   },
   "dependencies": {
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource-variable/source-serif-4": "^5.3.1",
     "@namostack/plugin-sdk": "workspace:*"
   },
   "devDependencies": {

package/templates/vanilla/public/icon.svg

@@ -1,4 +1,4 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
-  <rect width="64" height="64" rx="14" fill="#4f46e5" />
+  <rect width="64" height="64" rx="14" fill="#6344e5" />
   <path d="M22 16h13a11 11 0 0 1 0 22h-6v10h-7zm7 6v10h6a5 5 0 0 0 0-10z" fill="#fff" fill-rule="evenodd" />
 </svg>

package/templates/vanilla/src/main.ts

@@ -1,7 +1,37 @@
-import { connect, type PluginTheme } from '@namostack/plugin-sdk';
+import {
+  BridgeError,
+  connect,
+  type PluginTheme,
+  type StoredDocument,
+} from '@namostack/plugin-sdk';
+import './style.css';
+
+// seedui's fonts, as in the namostack app.
+import '@fontsource-variable/inter';
+import '@fontsource-variable/source-serif-4';
+
+interface Clicks {
+  count: number;
+}
 
 // Plugins only run inside the namostack app: anywhere else, this throws.
 const namostack = await connect();
+const { context, data, ui, user } = namostack;
+
+function element<T extends HTMLElement = HTMLElement>(id: string): T {
+  return document.getElementById(id) as T;
+}
+
+/** Shows a failed SDK call; a missing permission says how to add it. */
+function showError(target: HTMLElement, error: unknown, permission: string) {
+  target.hidden = false;
+  target.textContent =
+    error instanceof BridgeError && error.code === 'permission_denied'
+      ? `Add "${permission}" to the permissions in namostack.plugin.json.`
+      : error instanceof BridgeError
+        ? error.message
+        : String(error);
+}
 
 /** Follows the app's light or dark mode; style against `[data-mode="dark"]`. */
 function applyTheme({ mode }: PluginTheme) {
@@ -9,9 +39,120 @@ function applyTheme({ mode }: PluginTheme) {
   document.documentElement.style.colorScheme = mode;
 }
 
-applyTheme(namostack.context.theme);
+applyTheme(context.theme);
 namostack.onThemeChange(applyTheme);
 
-// textContent, not innerHTML: the name is the developer's own text.
-document.getElementById('root')!.textContent =
-  `Welcome to your namostack plugin ${namostack.context.name}`;
+// textContent, not innerHTML: these are the developer's and user's own text.
+element('name').textContent = context.name;
+document.querySelector('main')!.hidden = false;
+
+user
+  .getProfile()
+  .then(({ displayName }) => {
+    element('greeting').textContent =
+      `Hi ${displayName}, this is your new plugin.`;
+  })
+  .catch((error: unknown) =>
+    showError(element('greeting-error'), error, 'user:profile:read'),
+  );
+
+// A counter saved for the current user: it survives reloads and devices.
+const count = element('count');
+const increment = element<HTMLButtonElement>('increment');
+const reset = element<HTMLButtonElement>('reset');
+const countError = element('count-error');
+let clicks: StoredDocument<Clicks> | null = null;
+
+function render() {
+  count.textContent = String(clicks?.count ?? 0);
+  reset.disabled = !clicks;
+}
+
+/** Like seedui's `isLoading`: keeps the button's size and swaps its label for a spinner. */
+function setLoading(button: HTMLButtonElement, loading: boolean) {
+  if (loading) {
+    const { width, height } = button.getBoundingClientRect();
+
+    button.dataset.label = button.textContent ?? '';
+    button.style.width = `${width}px`;
+    button.style.height = `${height}px`;
+    button.replaceChildren(
+      Object.assign(document.createElement('div'), { className: 'spinner' }),
+    );
+  } else {
+    button.textContent = button.dataset.label ?? '';
+    button.style.width = '';
+    button.style.height = '';
+  }
+
+  button.ariaBusy = String(loading);
+}
+
+async function run(
+  button: HTMLButtonElement,
+  change: () => Promise<StoredDocument<Clicks> | null>,
+) {
+  const other = button === increment ? reset : increment;
+
+  setLoading(button, true);
+  other.disabled = true;
+  countError.hidden = true;
+
+  try {
+    clicks = await change();
+  } catch (error) {
+    showError(countError, error, 'storage');
+  } finally {
+    setLoading(button, false);
+    increment.disabled = false;
+    render();
+  }
+}
+
+increment.addEventListener('click', () => {
+  if (increment.ariaBusy === 'true') {
+    return;
+  }
+
+  void run(increment, () =>
+    clicks
+      ? data.update<Clicks>('clicks', clicks.id, { count: clicks.count + 1 })
+      : data.insert<Clicks>('clicks', { count: 1 }),
+  );
+});
+
+reset.addEventListener('click', () => {
+  if (reset.ariaBusy === 'true') {
+    return;
+  }
+
+  void run(reset, async () => {
+    if (clicks) {
+      await data.delete('clicks', clicks.id);
+    }
+
+    return null;
+  });
+});
+
+data
+  .find<Clicks>('clicks', { limit: 1 })
+  .then(({ items }) => {
+    clicks = items[0] ?? null;
+  })
+  .catch((error: unknown) => showError(countError, error, 'storage'))
+  .finally(() => {
+    increment.disabled = false;
+    render();
+  });
+
+// Shows a toast in the app, outside the plugin's frame.
+element('notify').addEventListener('click', async () => {
+  element('notify-error').hidden = true;
+
+  try {
+    await ui.notify({ message: 'Hello from your plugin!', tone: 'success' });
+  } catch (error) {
+    showError(element('notify-error'), error, 'ui:notify');
+  }
+});