@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/secret-value.md

@@ -0,0 +1,406 @@
+# SecretValue
+
+Masks a secret and adds reveal and copy buttons.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/SecretValue.tsx)
+
+## Overview
+
+SecretValue masks a secret behind 16 dots and adds reveal and copy buttons. A click anywhere on the block copies the value without revealing it.
+
+## Examples
+
+### Basic
+
+```tsx
+import { SecretValue, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <SecretValue label="API key" value="sk_demo_4eC39HqLyjWDarjtT1zdp7dc" {...styles.value()} />
+  )
+}
+
+namespace styles {
+  export const value = style({ maxWidth: '28rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/SecretValue/Basic.tsx)
+
+### Size
+
+Set `size` to `small`, `medium` (default), or `large`.
+
+```tsx
+import { SecretValue, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.column()}>
+      {(['small', 'medium', 'large'] as const).map((size) => (
+        <SecretValue
+          key={size}
+          label="API key"
+          size={size}
+          value="sk_demo_4eC39HqLyjWDarjtT1zdp7dc"
+        />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({
+    display: 'grid',
+    gap: '12',
+    gridTemplateColumns: 'minmax(0, 28rem) !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/SecretValue/Size.tsx)
+
+### DefaultRevealed
+
+Set `defaultRevealed` to start with the value shown.
+
+```tsx
+import { SecretValue, style } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <SecretValue
+      defaultRevealed
+      label="API key"
+      value="sk_demo_4eC39HqLyjWDarjtT1zdp7dc"
+      {...styles.value()}
+    />
+  )
+}
+
+namespace styles {
+  export const value = style({ maxWidth: '28rem !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/SecretValue/DefaultRevealed.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { SecretValue } from '@tempoxyz/ds'
+
+<SecretValue />
+```
+
+## Guidelines
+
+### When to Use
+
+* Show an API key, webhook signing secret, or access key that people copy into another system.
+* Show a recovery key that people must store, behind an explicit reveal.
+
+### When Not to Use
+
+* Use [Snippet](/docs/components/snippet) for commands and values that are not secret, such as a webhook URL.
+* Use [Hex](/docs/components/hex) with `copy` for public addresses and transaction hashes.
+* Use [TextInput](/docs/components/text-input) with `type="password"` when people enter a secret.
+
+### Start Masked
+
+Keep the value hidden until someone presses Reveal. Copy works without a reveal, and anyone near the screen or in a screen share can read a revealed value.
+
+* **`defaultRevealed`:** Set it only on a screen that exists to show the value, such as a key creation confirmation.
+* **Mask again:** Control `revealed` with `onRevealedChange` to mask the value again, such as when the tab is hidden or after a minute.
+
+**Do:** Show the secret masked, with its name above it.
+
+```tsx
+/** Do example for "Start Masked" on the SecretValue page: show the secret masked, with its name above it. @module */
+import { SecretValue, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span {...styles.label()}>Production API key</span>
+      <SecretValue label="Production API key" value="tk_live_9fA2c81bE07d4c55a3e6" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', gap: '8', width: '100% !custom' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+**Don't:** Reveal a secret by default on a page people return to, such as a key list.
+
+```tsx
+/**
+ * Don't example for "Start Masked" on the SecretValue page.
+ * Don't reveal a secret by default on a page people return to, such as a key list.
+ * @module
+ */
+import { SecretValue, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span {...styles.label()}>Production API key</span>
+      <SecretValue
+        defaultRevealed
+        label="Production API key"
+        value="tk_live_9fA2c81bE07d4c55a3e6"
+      />
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', gap: '8', width: '100% !custom' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+### Name Every Secret
+
+`label` sets the group's `aria-label`, which gives each button context. It is not visible. The mask is always 16 dots, so it can't tell keys apart either.
+
+**Do:** Show what each key unlocks above it, with a creation or last used date.
+
+```tsx
+/**
+ * Do example for "Name Every Secret" on the SecretValue page.
+ * Show what each key unlocks above it, with a creation or last used date.
+ * @module
+ */
+import { SecretValue, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.field()}>
+        <div {...styles.header()}>
+          <span {...styles.label()}>Production API key</span>
+          <span {...styles.meta()}>Last used 2 hours ago</span>
+        </div>
+        <SecretValue label="Production API key" size="small" value="tk_live_9fA2c81bE07d4c55a3e6" />
+      </div>
+      <div {...styles.field()}>
+        <div {...styles.header()}>
+          <span {...styles.label()}>Staging API key</span>
+          <span {...styles.meta()}>Created Oct 2</span>
+        </div>
+        <SecretValue label="Staging API key" size="small" value="tk_test_41bD7e0aC93f2d18b6c5" />
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', gap: '8' })
+
+  export const header = style({
+    alignItems: 'baseline',
+    display: 'flex',
+    gap: '12',
+    justifyContent: 'space-between',
+  })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const list = style({ display: 'grid', gap: '16', width: '100% !custom' })
+
+  export const meta = style({ color: 'content.secondary', typography: 'body.b3' })
+}
+```
+
+**Don't:** Leave people to tell keys apart by revealing them.
+
+```tsx
+/**
+ * Don't example for "Name Every Secret" on the SecretValue page.
+ * Don't leave people to tell keys apart by revealing them.
+ * @module
+ */
+import { SecretValue, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <SecretValue label="Production API key" size="small" value="tk_live_9fA2c81bE07d4c55a3e6" />
+      <SecretValue label="Staging API key" size="small" value="tk_test_41bD7e0aC93f2d18b6c5" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const list = style({ display: 'grid', gap: '16', width: '100% !custom' })
+}
+```
+
+### Keep Each Secret on One Line
+
+The value does not wrap, and a long revealed value scrolls horizontally.
+
+**Do:** Give a recovery phrase of 12 or 24 words its own numbered layout, behind the same explicit
+reveal.
+
+```tsx
+/**
+ * Do example for "Keep Each Secret on One Line" on the SecretValue page.
+ * Give a recovery phrase of 12 or 24 words its own numbered layout, behind the same explicit reveal.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+const words = [
+  'orbit',
+  'maple',
+  'ledger',
+  'canyon',
+  'velvet',
+  'harbor',
+  'quartz',
+  'ember',
+  'signal',
+  'meadow',
+  'falcon',
+  'summit',
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span {...styles.label()}>Recovery phrase</span>
+      <ol {...styles.grid()}>
+        {words.map((word, index) => (
+          <li key={word} {...styles.word()}>
+            <span {...styles.index()}>{index + 1}</span>
+            {word}
+          </li>
+        ))}
+      </ol>
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', gap: '8', width: '100% !custom' })
+
+  export const grid = style({
+    display: 'grid',
+    gap: '8',
+    gridTemplateColumns: 'repeat(3, 1fr) !custom',
+    listStyle: 'none',
+    margin: '0',
+    padding: '0',
+  })
+
+  export const index = style({ color: 'content.secondary', minWidth: '1.25rem !custom' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
+
+  export const word = style({
+    backgroundColor: 'container.regular',
+    borderRadius: '2xs',
+    color: 'content.primary',
+    display: 'flex',
+    gap: '4',
+    padding: '8',
+    typography: 'mono.m1',
+  })
+}
+```
+
+**Don't:** Put a recovery phrase in one scrolling line.
+
+```tsx
+/**
+ * Don't example for "Keep Each Secret on One Line" on the SecretValue page.
+ * Don't put a recovery phrase in one scrolling line.
+ * @module
+ */
+import { SecretValue, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span {...styles.label()}>Recovery phrase</span>
+      <SecretValue
+        defaultRevealed
+        label="Recovery phrase"
+        value="orbit maple ledger canyon velvet harbor quartz ember signal meadow falcon summit"
+      />
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', gap: '8', width: '100% !custom' })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })
+}
+```
+
+## Content
+
+* **Visibility:** If a key is shown once, write Store this key now. You can't view it again.
+* **Leaks:** Link to the replacement action, such as Rotate key.
+
+## Accessibility
+
+SecretValue renders a named `group` with a masked `<code>` value, a reveal toggle, and a copy button. Both buttons follow the [WAI-ARIA Authoring Practices button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/).
+
+### Semantics
+
+* **Root (group):** Takes its name from the `label` prop.
+* **Value (16 dots):** Screen readers read the dots, never the secret. The mask hides the length and blocks selection.
+* **Reveal Button (aria-pressed):** A native button named "Reveal" that reports whether the secret is shown.
+* **Copy Button (button):** A native button named "Copy". It reads "Copied" for two seconds, and a polite status region announces each copy.
+* **Pointer Shortcut (click):** A click on the block copies without a reveal. Keyboard users use the copy button.
+
+### Keyboard
+
+* **Move Between Buttons (Tab):** Moves focus to the reveal button, then to the copy button. The value takes no focus.
+* **Reveal or Copy (Enter or Space):** The reveal button shows or hides the secret. The copy button copies it. Focus stays on the pressed button.
+
+### Your Responsibilities
+
+* **Allow Paste (SC 3.3.8):** Do not block paste where people use the secret. [Accessible authentication](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html) relies on it.
+
+## Related
+
+[Snippet](/docs/components/snippet)
+
+Use for values that aren't secret.
+
+[CopyButton](/docs/components/copy-button)
+
+Use for copying beside your own layout.
+
+[TextInput](/docs/components/text-input)
+
+Use for entering a secret.
+
+[Destructive Actions](/docs/patterns/destructive-actions)
+
+Covers revoking and rotating keys.
+
+[Tempo Console](/docs/products/tempo-console)
+
+Covers API key screens.