@soulparking/design-system

@soulparking/design-system

SoulParking Design System — Vue 3 components published as framework-agnostic Web Components.

Full documentation & live component playground: spn-ds.balbalcode.my.id

Installation

npm install @soulparking/design-system

Usage

Option A — Web Components (React, Angular, Vanilla JS, any framework)

Register all custom elements once in your app entry point:

import '@soulparking/design-system/dist/es/web-components/index.js'
import '@soulparking/design-system/dist/style.css'

Then use the HTML tags anywhere:

<spn-button variant="primary" text="Click me"></spn-button>
<spn-input placeholder="Enter email"></spn-input>
<spn-badge variant="success" label="Active"></spn-badge>

Option B — Vue 3 Components (tree-shakeable)

import { ActionButton, InputTextGroup, DataTable } from '@soulparking/design-system'
import '@soulparking/design-system/dist/style.css'

Web Component Tags

Tag	Description
<spn-button>	Action button
<spn-input>	Text input
<spn-input-group>	Labeled input with hint + error
<spn-textarea>	Textarea
<spn-textarea-group>	Labeled textarea
<spn-select>	Select dropdown
<spn-select-group>	Labeled select
<spn-checkbox>	Checkbox
<spn-checkbox-group>	Labeled checkbox group
<spn-radio>	Radio button
<spn-radio-group>	Labeled radio group
<spn-switch>	Toggle switch
<spn-badge>	Status badge
<spn-tag>	Tag / chip
<spn-card-input>	Card-style selectable input
<spn-file-input>	File upload with drag-and-drop + S3 support
<spn-file-input-group>	Labeled file input
<spn-image-input-group>	Image upload with preview
<spn-pagination>	Pagination controls

Component Reference

<spn-button>

<spn-button
  variant="primary"
  text="Save"
  size="md"
  is-disabled="true"
></spn-button>

Prop	Values	Default
variant	primary secondary outline ghost danger	primary
size	sm md lg	md
text	string	—
is-disabled	"true"	—

<spn-input>

<spn-input
  placeholder="[e-mail]"
  is-password="true"
></spn-input>

<!-- With prefix icon (slot) -->
<spn-input placeholder="Email">
  <svg slot="prefix" ...></svg>
</spn-input>

Prop	Description
placeholder	Input placeholder
is-password	"true" — shows password toggle
disabled	"true"

Event: update:modelValue — fired on every keystroke with event.detail = current value.

<spn-input-group>

<spn-input-group
  label="Email address"
  hint="We'll never share your email."
  error="Required field"
  label-action="Forgot?"
></spn-input-group>

Prop	Description
label	Field label
hint	Helper text below the input
error	Error message (red state)
label-action	Clickable link text next to the label

Event: label-action-click — fired when the label action link is clicked.

<spn-file-input>

Drag-and-drop file upload widget with per-file progress, done, and error states. Supports S3 presigned URL upload.

<spn-file-input
  accept=".pdf,.docx"
  hint="PDF or DOCX up to 10MB"
  multiple="true"
  max-size="10"
  upload-endpoint="https://api.example.com/upload/presign"
  auth-token="Bearer eyJ..."
></spn-file-input>

Prop	Description
accept	MIME types or extensions (e.g. ".pdf,image/*")
hint	Helper text inside the drop zone
multiple	"true" — allow multiple files
max-size	Max file size in MB
upload-endpoint	URL to fetch a presigned upload URL
auth-token	Bearer token sent in Authorization header

The endpoint must return:

{ "url": "https://s3.amazonaws.com/...", "fields": { ... } }

Events: update:modelValue (array of uploaded URLs), upload-error, files

<spn-image-input-group>

Image upload with 16:9 preview.

<spn-image-input-group
  label="Cover photo"
  accept="image/*"
  upload-endpoint="https://api.example.com/upload/presign"
  auth-token="Bearer eyJ..."
  preview-base-url="https://cdn.example.com"
></spn-image-input-group>

<spn-badge>

<spn-badge variant="success" label="Active"></spn-badge>
<spn-badge variant="warning" label="Pending"></spn-badge>
<spn-badge variant="danger"  label="Inactive"></spn-badge>

variant
default success warning danger info

<spn-pagination>

<spn-pagination
  current-page="1"
  total-pages="10"
  per-page="10"
  total-items="98"
></spn-pagination>

Event: page-change — event.detail = new page number.

Framework Integration

React

Web Components emit CustomEvent, not React synthetic events. Wrap them with a small bridge:

import { useRef, useEffect, useCallback } from 'react'

function SpnInput({ value, onChange, ...props }) {
  const ref = useRef(null)

  useEffect(() => {
    if (ref.current) ref.current.modelValue = value ?? ''
  }, [value])

  const stable = useCallback(onChange, [])
  useEffect(() => {
    const el = ref.current
    if (!el) return
    const handler = (e) => stable(e.detail)
    el.addEventListener('update:modelValue', handler)
    return () => el.removeEventListener('update:modelValue', handler)
  }, [stable])

  return <spn-input ref={ref} {...props} />
}

Angular

Add CUSTOM_ELEMENTS_SCHEMA to your module or standalone component:

import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'

@Component({
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `<spn-input #inputRef placeholder="Email"></spn-input>`,
})
export class MyComponent implements AfterViewInit {
  @ViewChild('inputRef') inputRef!: ElementRef

  ngAfterViewInit() {
    this.inputRef.nativeElement
      .addEventListener('update:modelValue', (e: CustomEvent) => {
        this.value = e.detail
      })
  }
}

Vue 3

Use Vue components directly for full reactivity:

<script setup>
import { ref } from 'vue'
import { InputTextGroup, ActionButton } from '@soulparking/design-system'
import '@soulparking/design-system/dist/style.css'

const email = ref('')
</script>

<template>
  <InputTextGroup label="Email" v-model="email" />
  <ActionButton variant="primary" text="Submit" />
</template>

Documentation

Full interactive documentation is available at spn-ds.balbalcode.my.id, including:

• Live component playground (Storybook)
• All props, slots, and events per component
• Design tokens and color palette
• Copy-paste code examples for Vue, React, and Angular

Publishing

Requires Node 20+.

nvm use 20
npm version patch        # bump version
npm publish --otp 123456 # 6-digit code from authenticator

License

Private — SoulParking internal use.