@razerspine/pug-ui-kit 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Razerspine
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @razerspine/pug-ui-kit
+
+A collection of reusable Pug mixins designed for the [Webpack Starter Monorepo](https://github.com/Razerspine/webpack-starter-monorepo).
+
+This package centralizes UI components, ensuring consistency across all templates generated by the CLI.
+
+## 📦 Installation
+
+This package is automatically included in templates generated via the CLI. To install it manually:
+
+```bash
+npm install @razerspine/pug-ui-kit
+```
+
+## 🛠 Webpack Configuration
+
+To use these mixins efficiently without dealing with complex relative paths (e.g., ../../node_modules/...), configure a Webpack alias in your webpack.config.js:
+
+```js
+const pugMixinsPath = require('@razerspine/pug-ui-kit');
+
+module.exports = {
+  // ...
+  resolve: {
+    alias: {
+      // Create an alias 'pug-ui-kit' pointing to the mixins directory
+      'pug-ui-kit': pugMixinsPath,
+    },
+  },
+};
+```
+## 🚀 Usage
+
+Once the alias is configured, you can include any mixin in your .pug files using the ~pug-ui-kit/ prefix:
+
+### Example: Button (btn.pug)
+
+```
+include ~pug-ui-kit/btn.pug
+
++btn('Save', 'primary', 'small', {type: 'button'})
+```
+
+## 📂 Available Mixins
+
+The package currently includes the following components:
+
+* btn.pug - renders a configurable button with optional icon and text.  
+* data-table.pug - renders a flexible table from an array of objects.
+* form-input.pug - renders a configurable input element with optional label and placeholder. 
+* form-textarea.pug - renders a configurable textarea element with optional label and placeholder.
+* input-checkbox.pug - renders a configurable checkbox with label and optional attributes.
+* input-radio.pug — renders a configurable radio input with label for use in radio groups. 
+* single-select.pug - renders a configurable select element with label, options, and optional placeholder.
+
+## 📄 License
+This project is licensed under the ISC License.

package/index.js

@@ -0,0 +1,3 @@
+const path = require('path');
+
+module.exports = path.join(__dirname, 'mixins');

package/mixins/btn.pug

@@ -0,0 +1,103 @@
+//- Button mixin
+//- Renders a configurable button with optional icon and text. Visual appearance
+//- is primarily controlled by the `variant` and `size` parameters and by CSS
+//- classes applied via `attrs` or global styles.
+//-
+//- NOTE: project migrated to an SVG sprite. The mixin references symbols by id
+//- using <use href="#icon-{iconName}"> (xlink:href kept for legacy browsers).
+//- Ensure your sprite contains <symbol id="icon-{name}"> entries.
+//-
+//- Parameters:
+//-   text        - **String | null** — Visible button text. If `null` or an empty
+//-                 string, the text node is omitted (icon-only button).
+//-                 Default: null
+//-   variant     - **String** — Visual variant modifier appended to `.btn--{variant}`.
+//-                 Common values: 'primary', 'secondary', 'outline', 'text-primary',
+//-                 'text-secondary', 'icon-primary', 'icon-secondary', 'icon-outline', 'icon'.
+//-                 Default: 'primary'
+//-   size        - **String** — Size modifier appended to `.btn--{size}` and used
+//-                 for icon sizing `.icon--{size}`. Common values: 'small', 'medium', 'large'.
+//-                 Default: 'medium'
+//-   attrs       - **Object | null** — Attributes to spread onto the `<button>`
+//-                 element via `&attributes(attrs)`. Use this to pass `type`,
+//-                 `id`, `aria-*`, `data-*`, etc. If `null`, no attributes are spread.
+//-                 If `attrs.class` is present it will be merged with the base classes.
+//-                 Default: { type: 'button' }
+//-   iconName    - **String | null** — Icon name (without prefix). The mixin uses
+//-                 `#icon-{iconName}` in <use> to reference the SVG sprite symbol.
+//-                 If `null`, no icon is rendered.
+//-                 Default: null
+//-
+//- Accessibility notes:
+//-   - If the button has visible text, the SVG is treated as decorative and gets
+//-     `aria-hidden="true"` so screen readers ignore it.
+//-   - If the button is icon-only (text === null or empty), the mixin will set
+//-     `aria-label` on the button if `attrs` does not already provide one. Provide
+//-     a meaningful `aria-label` in `attrs` for icon-only buttons.
+//-
+//- Behavior summary:
+//-   - Computes `hasText` to decide whether to render the text node.
+//-   - Builds base classes and safely merges any `attrs.class` with them.
+//-   - Renders <svg><use href="#icon-{iconName}" xlink:href="#icon-{iconName}"></use></svg>
+//-     when `iconName` is provided.
+//-   - Sets `aria-hidden` on the SVG when text is present; ensures icon-only buttons
+//-     have an accessible label.
+//-
+//- Examples (corrected to match mixin signature):
+//-   // Primary sizes (text only)
+//-   +btn('Save', 'primary', 'small', {type: 'button'})
+//-   +btn('Save', 'primary', 'medium', {type: 'button'})
+//-   +btn('Save', 'primary', 'large', {type: 'button'})
+//-
+//-   // Secondary sizes (text only)
+//-   +btn('Cancel', 'secondary', 'small', {type: 'button'})
+//-   +btn('Cancel', 'secondary', 'medium', {type: 'button'})
+//-   +btn('Cancel', 'secondary', 'large', {type: 'button'})
+//-
+//-   // Outline variant (text only)
+//-   +btn('More', 'outline', 'small', {type: 'button'})
+//-   +btn('More', 'outline', 'medium', {type: 'button'})
+//-   +btn('More', 'outline', 'large', {type: 'button'})
+//-
+//-   // Button with icon and text
+//-   +btn('Settings', 'primary', 'small', {type: 'button'}, 'settings')
+//-   +btn('Settings', 'secondary', 'medium', {type: 'button'}, 'settings')
+//-   +btn('Settings', 'outline', 'large', {type: 'button'}, 'settings')
+//-
+//-   // Text-only style variants
+//-   +btn('Learn more', 'text-primary', 'medium', {type: 'button'})
+//-   +btn('Dismiss', 'text-secondary', 'medium', {type: 'button'})
+//-
+//-   // Icon-only buttons (pass null for text and use an icon-* variant)
+//-   // Provide aria-label in attrs or rely on mixin fallback to iconName -> label
+//-   +btn(null, 'icon-primary', 'medium', {type: 'button', 'aria-label': 'Settings'}, 'settings')
+//-   +btn(null, 'icon-secondary', 'small', {type: 'button', 'aria-label': 'Close'}, 'close')
+//-   +btn(null, 'icon-outline', 'large', {type: 'button'}, 'menu')
+//-
+//- Keep this docblock updated when you change parameter names, defaults, or
+//- the CSS variants so editor hover comments remain accurate.
+mixin btn(text, variant='primary', size='medium', attrs={'type':'button'}, iconName=null)
+  - const hasText = typeof text === 'string' && text.trim().length > 0;
+  - const baseClass = 'btn btn--' + variant + ' btn--' + size;
+  - const incomingClass = attrs && attrs.class ? String(attrs.class).trim() : '';
+  - const combinedClass = (incomingClass ? incomingClass + ' ' : '') + baseClass;
+  - // shallow copy attrs so we don't mutate caller object
+  - const safeAttrs = Object.assign({}, attrs || {});
+  - // ensure class is present in the attrs we pass to &attributes
+  - safeAttrs.class = combinedClass;
+  - // accessibility fallback for icon-only buttons
+  - if (!hasText && iconName && !(safeAttrs['aria-label'] || safeAttrs['ariaLabel'] || safeAttrs['aria-labelledby'])) {
+  -   safeAttrs['aria-label'] = iconName.replace(/[-_]/g, ' ');
+  - }
+  button&attributes(safeAttrs)
+    if iconName
+      - // build svgAttrs as a plain object without undefined values
+      - const svgAttrs = Object.assign(
+      -   {},
+      -   hasText ? { 'aria-hidden': 'true' } : { role: 'img' },
+      -   { class: 'button-icon icon--' + size }
+      - );
+      svg&attributes(svgAttrs)
+        use(xlink:href='#icon-' + iconName, href='#icon-' + iconName)
+    if hasText
+      | #{text}

package/mixins/data-table.pug

@@ -0,0 +1,112 @@
+//- dataTable mixin
+//- Renders a flexible table from an array of objects. Columns are derived
+//- from the provided `columns` array or automatically collected from object keys.
+//- Supports optional index column, optional actions column (slot), per-column
+//- formatters and custom header labels.
+//-
+//- Parameters:
+//-   items       - **Array** — Array of objects to render as rows. Each object
+//-                 represents one row; object keys map to columns. If not an
+//-                 array, an empty table is rendered.
+//-                 Example: [{ id:1, name:'Olya' }, { id:2, name:'Ivan' }]
+//-                 Default: []
+//-   columns     - **Array | undefined** — Optional ordered list of keys to use
+//-                 as columns. If omitted or empty, unique keys are collected
+//-                 from all objects in `items` and used in insertion order.
+//-                 Example: ['id','name','email']
+//-                 Default: auto-collected from items
+//-   options     - **Object | undefined** — Additional options:
+//-                 - emptyText: **String** — Text shown when no rows; Default: 'No data'.
+//-                 - showIndex: **Boolean** — Render leading index column; Default: false.
+//-                 - showActions: **Boolean** — Render trailing Actions column (slot); Default: true.
+//-                 - formatters: **Object** — Map of column -> function(value) for custom rendering.
+//-                   Example: { createdAt: v => new Date(v).toLocaleDateString() }.
+//-                 - labels: **Object** — Map of column -> header label string. If absent,
+//-                   header is generated by humanizing the key (underscores -> spaces, capitalized).
+//-                 Default: {}
+//-
+//- Behavior:
+//-   - If `items` is empty, a single header cell spanning all columns displays `emptyText`.
+//-   - Column order follows `columns` if provided; otherwise it follows the unique keys
+//-     discovered across `items`.
+//-   - For each cell, `formatters[col]` is used when present; otherwise arrays are joined,
+//-     objects are JSON-stringified, and primitives are stringified.
+//-   - The Actions column is a slot: when `showActions` is true, the mixin renders a `td`
+//-     containing the caller-provided block. Inside the block the current row object is
+//-     available as `item` and the row index as `i`.
+//-
+//- Notes and best practices:
+//-   - Prefer passing an explicit `columns` array when you need stable column order.
+//-   - Use `labels` for human-friendly or localized header text instead of renaming keys.
+//-   - Keep `formatters` pure and return safe strings; if returning HTML, use `!=` in the mixin call
+//-     or return already-escaped content carefully to avoid XSS.
+//-   - To hide the Actions column entirely, set `showActions: false` in `options`.
+//-   - For large datasets, consider server-side pagination or client-side slicing before passing `items`.
+//-
+//- Examples:
+//-   // Basic usage with auto columns
+//-   - const data = [{ id:1, name:'Olya' }, { id:2, name:'Ivan' }]
+//-   +dataTable(data)
+//-
+//-   // Explicit columns, labels and formatters
+//-   +dataTable(data, ['id','name'], {
+//-     showIndex: true,
+//-     showActions: false,
+//-     labels: { id: 'ID', name: 'Full name' },
+//-     formatters: { id: v => '#' + v }
+//-   })
+//-
+//-   // With Actions slot (edit/delete links). Inside block `item` is current row.
+//-   +dataTable(data, ['id','name'], { showActions: true })
+//-     a(href='/edit/#{item && item.id || ""}') Edit
+//-     |
+//-     a(href='/delete/#{item && item.id || ""}') Delete
+//-
+//- Keep this docblock updated when you change parameter names, defaults, or
+//- the mixin behavior so editor hover comments remain accurate.
+mixin dataTable(items, columns, options)
+  - const _items = Array.isArray(items) ? items : [];
+  - const cols = Array.isArray(columns) && columns.length ? columns : Array.from(new Set(_items.reduce((acc, it) => acc.concat(Object.keys(it || {})), [])));
+  - const opts = Object.assign({ emptyText: 'No data', showIndex: false, showActions: false, formatters: {}, labels: {} }, options || {});
+
+  - const humanize = function(key) {
+  -   if (!key && key !== 0) return '';
+  -   const s = String(key).replace(/_/g, ' ');
+  -   return s.charAt(0).toUpperCase() + s.slice(1);
+  - }
+
+  - const formatValue = function(v, col) {
+  -   if (v === null || v === undefined || v === '') return '';
+  -   if (opts.formatters && typeof opts.formatters[col] === 'function') return opts.formatters[col](v);
+  -   if (Array.isArray(v)) return v.join(', ');
+  -   if (typeof v === 'object') return JSON.stringify(v);
+  -   return String(v);
+  - }
+
+  if !_items.length
+    table.table
+      thead
+        tr
+          th(colspan=cols.length + (opts.showIndex ? 1 : 0) + (opts.showActions ? 1 : 0)) #{opts.emptyText}
+  else
+    table.table
+      thead
+        tr
+          if opts.showIndex
+            th #
+          each col in cols
+            - const label = (opts.labels && Object.prototype.hasOwnProperty.call(opts.labels, col)) ? opts.labels[col] : humanize(col)
+            th #{label}
+          if opts.showActions
+            th Actions
+      tbody
+        each item, i in _items
+          tr
+            if opts.showIndex
+              td #{i + 1}
+            each col in cols
+              - const val = (item && Object.prototype.hasOwnProperty.call(item, col)) ? item[col] : ''
+              td!= formatValue(val, col)
+            if opts.showActions
+              td
+                block

package/mixins/form-input.pug

@@ -0,0 +1,68 @@
+//- Form input mixin
+//- Renders a configurable <input> element with optional label and placeholder.
+//- Supports different input types, custom name, value, and placeholder text.
+//-
+//- Parameters:
+//-   type        - **String** — Input type attribute.
+//-                 Example: 'text', 'email', 'password', 'number'.
+//-                 Default: none (required).
+//-   id          - **String** — Unique identifier for the <input> element.
+//-                 Also used by the <label> `for` attribute.
+//-                 Example: 'username', 'email'.
+//-                 Default: none (required).
+//-   label       - **String | null** — Visible label text. If `null` or empty,
+//-                 no label is rendered.
+//-                 Example: 'Name', 'Email address'.
+//-                 Default: null.
+//-   placeholder - **String** — Placeholder text displayed inside the input
+//-                 when empty.
+//-                 Example: 'Enter your name', 'example@mail.com'.
+//-                 Default: ''.
+//-   name        - **String** — Name attribute for form submission.
+//-                 Example: 'username', 'email'.
+//-                 Default: ''.
+//-   value       - **String** — Default value for the input field.
+//-                 Example: 'John Doe', 'test@mail.com'.
+//-                 Default: ''.
+//-
+//- Behavior:
+//-   - The input always has `.form-control` class for styling.
+//-   - The label, if provided, uses `.form-label` class and is linked via `for=id`.
+//-   - The placeholder text is shown until the user types content.
+//-   - The `name` attribute ensures the input value is submitted with the form.
+//-   - The `value` attribute pre-fills the input field if provided.
+//-
+//- Notes about styling and classes:
+//-   - Visual appearance is controlled by `.form-control` and `.form-label`
+//-     styles in your SCSS.
+//-   - To add custom classes or attributes, extend the mixin or wrap it.
+//-   - Ensure `id` is unique to avoid duplicate `for`/`id` collisions.
+//-
+//- Examples:
+//-   // Basic text input
+//-   +formInput('text', 'name', 'Name', 'Enter your name', 'name')
+//-
+//-   // Email input with placeholder
+//-   +formInput('email', 'email', 'Email', 'example@mail.com', 'email')
+//-
+//-   // Password input
+//-   +formInput('password', 'password', 'Password', 'Enter password', 'password')
+//-
+//-   // Input with default value
+//-   +formInput('text', 'username', 'Username', 'Enter username', 'username', 'JohnDoe')
+//-
+//-   // Multiple inputs in a form
+//-   form.form
+//-     +formInput('text', 'first-name', 'First Name', 'Enter first name', 'firstName')
+//-     +formInput('text', 'last-name', 'Last Name', 'Enter last name', 'lastName')
+//-     +formInput('email', 'email', 'Email', 'example@mail.com', 'email')
+mixin formInput(type, id, label, placeholder='', name='', value='')
+  if label
+    label.form-label(for=id)= label
+  input.form-control(
+    type=type,
+    id=id,
+    name=name,
+    value=value,
+    placeholder=placeholder
+  )

package/mixins/form-textarea.pug

@@ -0,0 +1,55 @@
+//- Form textarea mixin
+//- Renders a configurable <textarea> element with optional label and placeholder.
+//- Supports custom name attribute for form submission.
+//-
+//- Parameters:
+//-   id          - **String** — Unique identifier for the <textarea> element.
+//-                 Also used by the <label> `for` attribute.
+//-                 Example: 'message', 'comment'.
+//-                 Default: none (required).
+//-   label       - **String | null** — Visible label text. If `null` or empty,
+//-                 no label is rendered.
+//-                 Example: 'Message', 'Comment'.
+//-                 Default: null.
+//-   placeholder - **String** — Placeholder text displayed inside the textarea
+//-                 when empty.
+//-                 Example: 'Type your message...', 'Enter comment here'.
+//-                 Default: ''.
+//-   name        - **String** — Name attribute for form submission.
+//-                 Example: 'message', 'feedback'.
+//-                 Default: ''.
+//-
+//- Behavior:
+//-   - The textarea always has `.form-textarea` class for styling.
+//-   - The label, if provided, uses `.form-label` class and is linked via `for=id`.
+//-   - The placeholder text is shown until the user types content.
+//-   - The `name` attribute ensures the textarea value is submitted with the form.
+//-
+//- Notes about styling and classes:
+//-   - Visual appearance is controlled by `.form-textarea` and `.form-label`
+//-     styles in your SCSS.
+//-   - To add custom classes or attributes, extend the mixin or wrap it.
+//-   - Ensure `id` is unique to avoid duplicate `for`/`id` collisions.
+//-
+//- Examples:
+//-   // Basic textarea with label and placeholder
+//-   +formTextarea('message', 'Message', 'Type your message...', 'message')
+//-
+//-   // Textarea without label
+//-   +formTextarea('comment', null, 'Enter comment here', 'comment')
+//-
+//-   // Textarea with custom name
+//-   +formTextarea('feedback', 'Feedback', 'Write your feedback...', 'feedback')
+//-
+//-   // Multiple text areas in a form
+//-   form.form
+//-     +formTextarea('bio', 'Biography', 'Tell us about yourself', 'bio')
+//-     +formTextarea('notes', 'Notes', 'Additional notes...', 'notes')
+mixin formTextarea(id, label, placeholder='', name='')
+  if label
+    label.form-label(for=id)= label
+  textarea.form-textarea(
+    id=id,
+    name=name,
+    placeholder=placeholder
+  )

package/mixins/input-checkbox.pug

@@ -0,0 +1,50 @@
+//- inputCheckbox mixin
+//- Renders a configurable checkbox with label and optional attributes.
+//-
+//- Summary
+//-   Renders a checkbox input and its label inside a single inline control.
+//-   Uses the project's base input styles so visual appearance is driven by SCSS.
+//-
+//- Parameters
+//-   id        - **String** — Unique id for the <input>. Also used by <label for>.
+//-               Required; example: 'agree'.
+//-   label     - **String** — Visible label text shown next to the checkbox.
+//-               Required; example: 'I agree to terms'.
+//-   name      - **String** — Name attribute for form submission/grouping.
+//-               Optional; default: ''.
+//-   value     - **String** — Value submitted when checked. Optional; default: 'on'.
+//-   checked   - **Boolean** — Whether the checkbox is checked by default.
+//-               Optional; default: false.
+//-
+//- Behavior
+//-   - Wraps input and label in a single inline control element (uses .check-control-label).
+//-   - Input uses base input class (.input-base) so theme styles apply consistently.
+//-   - Label text is rendered in a sibling element (.input-text) and is clickable.
+//-   - If checked is true, the input is rendered with the checked attribute.
+//-   - Any attributes passed via attrs are applied to the <input> (useful for disabled, required, aria-*).
+//-
+//- Styling and accessibility
+//-   - Visual styling is controlled by .input-base, input[type="checkbox"], .check-control-label and .input-text in SCSS.
+//-   - Ensure id is unique to keep label association correct for screen readers.
+//-   - Prefer passing ARIA attributes via attrs for additional accessibility.
+//-
+//- Examples
+//-   // Basic checkbox
+//-   +inputCheckbox('agree', 'I agree to all terms')
+//-
+//-   // With name and custom value
+//-   +inputCheckbox('subscribe', 'Subscribe', 'newsletter', 'yes')
+//-
+//-   // Checked by default and disabled
+//-   +inputCheckbox('updates', 'Receive updates', 'updates', 'true', true, {disabled: true})
+//-
+mixin inputCheckbox(id, label, name='', value='on', checked=false)
+  label.check-control-label(for=id)
+    input.input-base(
+      type='checkbox',
+      id=id,
+      name=name,
+      value=value,
+      checked=checked,
+    )
+    span.input-text(data-i18n=label)= label

package/mixins/input-radio.pug

@@ -0,0 +1,53 @@
+//- inputRadio mixin
+//- Renders a configurable radio input with label for use in radio groups.
+//-
+//- Summary
+//-   Renders a single radio control paired with a clickable label.
+//-   Intended for groups where multiple radios share the same name.
+//-
+//- Parameters
+//-   id        - **String** — Unique id for the <input>. Also used by <label for>.
+//-               Required; example: 'contact-email'.
+//-   label     - **String** — Visible label text shown next to the radio.
+//-               Required; example: 'Email'.
+//-   name      - **String** — Name attribute to group radios. Required; example: 'contact'.
+//-   value     - **String** — Value submitted when selected. Required; example: 'email'.
+//-   checked   - **Boolean** — Whether this radio is selected by default.
+//-               Optional; default: false.
+//-
+//- Behavior
+//-   - Wraps input and label in a single inline control (.check-control-label).
+//-   - Input uses .input-base so theme styles apply consistently.
+//-   - Radios with the same name are mutually exclusive; only one can be selected.
+//-   - If checked is true, the input is rendered with the checked attribute.
+//-   - Any attrs are applied to the <input> (useful for disabled, required, aria-*).
+//-
+//- Styling and accessibility
+//-   - Visual styling is controlled by .input-base, input[type="radio"], .check-control-label and .input-text in SCSS.
+//-   - Ensure id is unique to keep label association correct for screen readers.
+//-
+//- Examples
+//-   // Basic radio group
+//-   .form-group
+//-     .input-group
+//-       span.form-label.w-100 Communication method
+//-       +inputRadio('contact-email', 'Email', 'contact', 'email')
+//-       +inputRadio('contact-phone', 'Phone', 'contact', 'phone')
+//-
+//-   // Vertical radio group
+//-   .form-group
+//-     .input-group.input-group--vertical
+//-       span.form-label.w-100 Gender
+//-       +inputRadio('gender-male', 'Male', 'gender', 'male', true)
+//-       +inputRadio('gender-female', 'Female', 'gender', 'female')
+//-
+mixin inputRadio(id, label, name, value, checked=false)
+  label.check-control-label(for=id)
+    input.input-base(
+      type='radio',
+      id=id,
+      name=name,
+      value=value,
+      checked=checked,
+    )
+    span.input-text(data-i18n=label)= label

package/mixins/single-select.pug

@@ -0,0 +1,92 @@
+//- singleSelect mixin
+//- Renders a configurable <select> element with label, options, and optional placeholder.
+//- Supports both arrays of strings and arrays of objects with configurable
+//- keys for label and value. Provides ability to set a default selected option.
+//-
+//- Parameters:
+//-   id             - **String** — Unique identifier for the <select> element.
+//-                    Also used as the `name` attribute.
+//-                    Example: 'topic', 'country'.
+//-                    Default: none (required).
+//-   label          - **String | null** — Visible label text. If `null` or empty,
+//-                    no label is rendered.
+//-                    Example: 'Topic', 'Choose country'.
+//-                    Default: null.
+//-   options        - **Array** — Options to render. Can be:
+//-                      - Array of strings: ['Support', 'Feedback', 'Other']
+//-                      - Array of objects: [{value:'support', text:'Support'}, …]
+//-                      - Array of objects with custom keys (see labelKey/valueKey).
+//-                    Default: [].
+//-   labelKey       - **String** — Key name in option objects for display text.
+//-                    Example: 'text', 'label'.
+//-                    Default: 'text'.
+//-   valueKey       - **String** — Key name in option objects for option value.
+//-                    Example: 'value', 'id'.
+//-                    Default: 'value'.
+//-   selectedValue  - **String** — Value of the option that should be selected
+//-                    by default. If empty, no option is preselected.
+//-                    Example: 'feedback', '2'.
+//-                    Default: ''.
+//-   placeholder    - **String** — Text for a placeholder option. Rendered only
+//-                    if `label` is null and `selectedValue` is empty.
+//-                    Example: 'Choose an option', 'Select country'.
+//-                    Default: 'Choose an option'.
+//-
+//- Behavior:
+//-   - If `options` is an array of strings, each string is used as both
+//-     the option value and label.
+//-   - If `options` is an array of objects, the keys defined by `labelKey`
+//-     and `valueKey` are used.
+//-   - The option whose value matches `selectedValue` is rendered with
+//-     the `selected` attribute.
+//-   - If no label is provided and no selectedValue is set, a placeholder
+//-     option is rendered at the top (`disabled selected hidden`).
+//-   - The <select> element always has `.single-select` class for styling.
+//-   - The label, if provided, uses `.form-label` class.
+//-
+//- Notes about styling and classes:
+//-   - Visual appearance is controlled by `.single-select` and `.form-label`
+//-     styles in your SCSS.
+//-   - To add custom classes or attributes, extend the mixin or wrap it.
+//-   - Ensure `id` is unique to avoid duplicate `for`/`id` collisions.
+//-
+//- Examples:
+//-   // Simple array of strings
+//-   +singleSelect('topic1', 'Topic', ['Support', 'Feedback', 'Other'])
+//-
+//-   // Array of objects with value/text
+//-   +singleSelect('topic2', 'Topic', [
+//-     {value:'support', text:'Support'},
+//-     {value:'feedback', text:'Feedback'},
+//-     {value:'other', text:'Other'}
+//-   ])
+//-
+//-   // Array of objects with id/label, custom keys
+//-   +singleSelect('topic3', 'Topic', [
+//-     {id:'1', label:'Support'},
+//-     {id:'2', label:'Feedback'}
+//-   ], 'label', 'id')
+//-
+//-   // With default selected value
+//-   +singleSelect('topic4', 'Topic', [
+//-     {value:'support', text:'Support'},
+//-     {value:'feedback', text:'Feedback'},
+//-     {value:'other', text:'Other'}
+//-   ], 'text', 'value', 'feedback')
+//-
+//-   // Without label, with placeholder
+//-   +singleSelect('topic5', null, [
+//-     {value:'support', text:'Support'},
+//-     {value:'feedback', text:'Feedback'},
+//-     {value:'other', text:'Other'}
+//-   ], 'text', 'value', '', 'Please select a topic')
+mixin singleSelect(id, label, options, labelKey='text', valueKey='value', selectedValue='', placeholder='Choose an option')
+  if label
+    label.form-label(for=id data-i18n=label)= label
+  select.single-select(id=id, name=id required)
+    if !label && !selectedValue
+      option(value='', disabled, selected, hidden data-i18n=placeholder)= placeholder
+    each opt in options
+      - let value = typeof opt === 'string' ? opt : opt[valueKey];
+      - let textKey = typeof opt === 'string' ? opt : opt[labelKey];
+      option(value=value, data-opt-value=value, selected=(value === selectedValue), data-i18n=textKey)= textKey

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@razerspine/pug-ui-kit",
+  "version": "1.0.0",
+  "description": "Shared Pug mixins for Webpack Starter templates",
+  "main": "index.js",
+  "files": [
+    "mixins",
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Razerspine",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Razerspine/webpack-starter-monorepo",
+    "directory": "packages/pug-ui-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/Razerspine/webpack-starter-monorepo/issues"
+  },
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  }
+}