@deadragdoll/reactnu 0.1.18 → 0.1.24

package/dist/styles.css

@@ -542,6 +542,73 @@
 .nu-info__accent[data-upper] {
   text-transform: uppercase;
 }
+.nu-icon-grid {
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  user-select: none;
+}
+.nu-icon-grid__icon {
+  position: absolute;
+  display: grid;
+  grid-template-rows: 3.25rem minmax(0, 2.2em);
+  justify-items: center;
+  width: 6rem;
+  height: 6rem;
+  padding: 0.25rem;
+  border: 1px solid transparent;
+  background: transparent;
+  color: var(--nu-text-primary);
+  font: inherit;
+  line-height: 1.1;
+  text-align: center;
+  cursor: default;
+  touch-action: none;
+}
+.nu-icon-grid__icon:focus-visible,
+.nu-icon-grid__icon[data-selected] {
+  border-color: var(--nu-border-light);
+  outline: 1px solid var(--nu-border-dark);
+  outline-offset: -3px;
+  background: var(--nu-color-title-bg);
+  color: var(--nu-text-inverse);
+}
+.nu-icon-grid__icon[data-dragging] {
+  z-index: 1;
+}
+.nu-icon-grid__icon:disabled {
+  opacity: 0.6;
+}
+.nu-icon-grid__glyph {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 3rem;
+  height: 3rem;
+  color: var(--nu-text-hotkey);
+}
+.nu-icon-grid__glyph > img,
+.nu-icon-grid__glyph > svg {
+  display: block;
+  max-width: 100%;
+  max-height: 100%;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+.nu-icon-grid__label {
+  display: -webkit-box;
+  max-width: 100%;
+  overflow: hidden;
+  overflow-wrap: anywhere;
+  text-overflow: ellipsis;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
+}
 .nu-listbox {
   flex: 1 1 auto;
   align-self: stretch;

package/docs/API_REFERENCE.md

@@ -39,6 +39,8 @@ See: [Slot Customization](./SLOT_CUSTOMIZATION.md)
 - `useNuWindowManager()`
   opens, updates, activates, and closes managed windows
   also exposes `showMessageBox(...)` and `showInputBox(...)`
+- `useNuIconManager()`
+  manages icons inside a `NuIconProvider`
 - `usePopupMenu()`
   anchor/open helper for `PopupMenu`
 - `useWindowMenu()`
@@ -113,6 +115,8 @@ See: [Slot Customization](./SLOT_CUSTOMIZATION.md)
   docs: [MainMenu](./MainMenu.md)
 - `PopupMenu`
   docs: [PopupMenu](./PopupMenu.md)
+- `NuIconProvider`, `NuIconGrid`
+  docs: [Icon Grid](./IconGrid.md)
 
 ## Windowing And Desktop Chrome
 

package/docs/COMPONENT_INDEX.md

@@ -19,6 +19,7 @@
 - [Frame](./Frame.md)
 - [Glyph](./Glyph.md)
 - [Info](./Info.md)
+- [Icon Grid](./IconGrid.md)
 - [ListBox](./ListBox.md)
 - [ListView](./ListView.md)
 - [MainMenu](./MainMenu.md)

package/docs/Desktop.md

@@ -21,6 +21,19 @@
 - `appBarContent?: ReactNode`
 - standard `div` props
 
+## Application icons
+
+`NuDesktop` does not own a separate icon implementation. Compose a reusable
+`NuIconProvider` and `NuIconGrid` inside the desktop workspace instead. The
+same pair can also live inside a `Window`.
+
+Use `NuIconGrid`'s `contextMenuItems` callback for a desktop background menu.
+It receives `useNuIconManager()`'s methods, so an `Arrange icons` submenu can
+call `arrangeIcons("columns")`, `arrangeIcons("rows")`, or
+`arrangeIcons("name")`.
+
+See [Icon Grid](./IconGrid.md) for the full API and interaction contract.
+
 ## Notes
 
 - The desktop owns the browser viewport and is intended to behave like a bounded screen.

package/docs/IconGrid.md

@@ -0,0 +1,93 @@
+# Icon Grid
+
+`NuIconProvider` owns a mutable collection of application icons. Place a
+`NuIconGrid` anywhere inside it: on the desktop, in a `Window`, or in another
+bounded surface.
+
+```tsx
+import {
+  NuIconGrid,
+  NuIconProvider,
+  useNuIconManager
+} from "@deadragdoll/reactnu";
+
+function Applications() {
+  return (
+    <NuIconProvider
+      defaultIcons={[
+        {
+          id: "diagnostics",
+          icon: "/icons/diagnostics.svg",
+          label: "&Diagnostics",
+          onDoubleClick: () => openDiagnostics()
+        }
+      ]}
+    >
+      <NuIconGrid
+        defaultArrangeMode="columns"
+        contextMenuItems={(icons) => [
+          {
+            id: "arrange-icons",
+            items: [
+              {
+                id: "arrange-by-name",
+                text: "&By name",
+                onSelect: () => icons.arrangeIcons("name")
+              }
+            ],
+            text: "&Arrange icons"
+          }
+        ]}
+      />
+    </NuIconProvider>
+  );
+}
+```
+
+## API
+
+`NuIconProvider`
+
+- `defaultIcons?: NuIconDefinition[]` seeds its internal collection. IDs should
+  be unique; omitted IDs are generated.
+- Icon `icon` accepts a URL string for SVG, PNG, or JPEG assets, or inline
+  React content such as an `<svg>`.
+
+`NuIconGrid`
+
+- `contextMenuItems` accepts ordinary `MainMenuNode[]` or a callback receiving
+  the icon manager. Use the callback for a background menu such as Arrange
+  icons.
+- `defaultArrangeMode="columns" | "rows" | "name"` arranges seeded icons
+  once, after the grid measures a non-zero available area. This prevents icons
+  from initially landing outside a bounded `Window`.
+
+`useNuIconManager()`
+
+- `addIcon(definition)` returns the new icon ID.
+- `updateIcon(id, patch)`, `removeIcon(id)`, `moveIcon(id, position)`, and
+  `selectIcon(id | null)` update the provider collection.
+- `arrangeIcons("columns" | "rows" | "name")` lays out the current icons.
+
+Each icon can have `onClick`, `onDoubleClick`, `onContextMenu`,
+`onPositionChange`, and its own `contextMenuItems`.
+
+## Interaction and accessibility
+
+- Drag icons to move them inside the grid; their resulting positions remain in
+  the provider for the lifetime of that provider.
+- A click selects an icon. Enter and Space activate its normal button action.
+- Right-click opens the icon menu; `Shift+F10` and the Context Menu key open it
+  from the keyboard.
+- Right-click the grid background for the grid context menu, such as Arrange
+  icons. An `onContextMenu` handler may call `preventDefault()` to replace it.
+- Labels wrap to two lines. Longer labels receive an ellipsis; long unbroken
+  words are wrapped instead of overflowing their icon cell.
+
+## Persistence
+
+The provider keeps icon positions for its mounted lifetime. To restore a layout
+after a reload, save a position from `onPositionChange` and pass it back as the
+icon's `position` in `defaultIcons` on the next mount. Call `arrangeIcons(...)`
+only for an explicit user action, rather than on every render, so a saved layout
+is not overwritten.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deadragdoll/reactnu",
-  "version": "0.1.18",
+  "version": "0.1.24",
   "private": false,
   "description": "React components with a precise DOS-era utility interface.",
   "license": "MIT",