@startupjs-ui/avatar 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [0.1.3](https://github.com/startupjs/startupjs-ui/compare/v0.1.2...v0.1.3) (2025-12-29)
+
+**Note:** Version bump only for package @startupjs-ui/avatar
+
+
+
+
+
+## [0.1.2](https://github.com/startupjs/startupjs-ui/compare/v0.1.1...v0.1.2) (2025-12-29)
+
+
+### Features
+
+* add mdx and docs packages. Refactor docs to get rid of any @startupjs/ui usage and use startupjs-ui instead ([703c926](https://github.com/startupjs/startupjs-ui/commit/703c92636efb0421ffd11783f692fc892b74018f))
+* **avatar:** refactor Avatar component ([768b74f](https://github.com/startupjs/startupjs-ui/commit/768b74f47dde3b7fcfe2804d340c69fb31ab7ce0))

package/README.mdx

@@ -0,0 +1,152 @@
+import { useState, useCallback } from 'react'
+import { pug, styl } from 'startupjs'
+import Avatar, { _PropsJsonSchema as AvatarPropsJsonSchema } from './index'
+import Div from '@startupjs-ui/div'
+import Span from '@startupjs-ui/span'
+import Br from '@startupjs-ui/br'
+import { Sandbox } from '@startupjs-ui/docs'
+
+# Avatar
+
+Avatars can be used to represent people. When used with a specific logo, avatars can also be used to represent a brand. They also can be a placeholder when there is no image or image can't be loaded by some reason to be shown, showing an alternative in this case.
+
+```js
+import { Avatar } from 'startupjs-ui'
+```
+
+## Simple example
+
+```jsx example
+return pug`
+  Avatar(src='/img/avatar1.jpeg')
+`
+```
+
+## Sizes
+Size is `m` by default. It can be changed by changing the `size` property by setting it to one of the values ​​('s', 'm', 'l') or by specifying the size in pixels.
+
+```jsx example
+return pug`
+  Div(row)
+    Div
+      Avatar(
+        size='s'
+        src='/img/avatar2.jpeg'
+      )
+    Div(pushed)
+      Avatar(
+        size='m'
+        src='/img/avatar3.jpeg'
+      )
+    Div(pushed)
+      Avatar(
+        size='l'
+        src='/img/avatar1.jpeg'
+      )
+    Div(pushed)
+      Avatar(
+        size=60
+        src='/img/avatar3.jpeg'
+      )
+`
+```
+
+## User status
+Avatars can be used to display user online status. It can be set by passing string `online` or `away` to property `status`.
+
+```jsx example
+return pug`
+  Div(row)
+    Div
+      Avatar(
+        status='online'
+        src='/img/avatar1.jpeg'
+      )
+    Div(pushed)
+      Avatar(
+        status='away'
+        src='/img/avatar2.jpeg'
+      )
+`
+```
+
+Also you can provide custom components for the status icon using `statusComponents` prop.
+
+```jsx example
+const AbsentStatus = useCallback(({ style }) => (
+  <Div style={style} styleName='absent'>
+    <Div styleName='absent-line absent-line-1' />
+    <Div styleName='absent-line absent-line-2' />
+  </Div>
+))
+
+return pug`
+  Avatar(
+    pushed
+    src='/img/avatar2.jpeg'
+    status='absent'
+    statusComponents={
+      absent: AbsentStatus
+    }
+  )
+`
+
+styl`
+  .absent
+    background-color white
+    justify-content center
+    &-line
+      position absolute
+      height 2px
+      left 0
+      right 0
+      background-color red
+      &-1
+        transform rotate(45deg)
+      &-2
+        transform rotate(-45deg)
+`
+```
+
+## Fallback string
+If `url` prop is not provided or if there is an error loading the avatar image, the component using an alternative. The alternative is initials of two first words of `children` string if provided and `?` if not. In the example below alternative is 'John Doe' therefore 'JD' will be displayed.
+
+```jsx example
+return pug`
+  Div(row)
+    Div
+      Avatar(src='/img/non-existen-image.jpeg')
+    Div(pushed)
+      Avatar(
+        src='/img/non-existen-image.jpeg'
+      ) John Doe
+`
+```
+
+## Actions
+
+Passed handler to `onPress` property will be called when the user taps the component.
+
+```jsx example
+const [counter, setCounter] = useState(0)
+
+return pug`
+  Div
+    Avatar(
+      src='/img/avatar1.jpeg'
+      onPress=()=> setCounter(counter + 1)
+    )
+    Br
+    Span= 'Clicked ' + counter + ' times'
+`
+```
+
+## Sandbox
+
+<Sandbox
+  Component={Avatar}
+  propsJsonSchema={AvatarPropsJsonSchema}
+  props={{
+    onPress: () => alert('"onPress" event on "Avatar" component'),
+  }}
+/>

package/index.cssx.styl

@@ -0,0 +1,62 @@
+$this = merge(
+  {
+    avatarSizes: {
+      s: 4u,
+      m: 5u,
+      l: 6u,
+    },
+    statusSizes: {
+      s: 1.25u,
+      m: 1.5u,
+      l: 1.75u,
+    },
+    fallbackSizes: {
+      s: 1.5u,
+      m: 1.75u,
+      l: 2u,
+    }
+  },
+  $UI.Avatar,
+  true
+)
+
+.root
+  +web()
+    user-select none
+
+.avatarWrapper
+  height 100%
+  overflow hidden
+
+.avatar
+  justify-content center
+  align-items center
+  height 100%
+
+.fallback
+  color var(--color-text-on-color)
+
+.status
+  position absolute
+  z-index 1
+  border-width 2px
+  border-color var(--color-border-main-strong)
+  radius(circle)
+
+  &.circle
+    right 0
+    bottom 0
+
+  &.squared
+  &.rounded
+    bottom -0.25u
+    right @bottom
+
+  &.online
+    background-color var(--color-bg-success)
+
+  &.away
+    background-color var(--color-bg-warning)
+
+:export
+  config: $this

package/index.d.ts

@@ -0,0 +1,25 @@
+/* eslint-disable */
+// DO NOT MODIFY THIS FILE - IT IS AUTOMATICALLY GENERATED ON COMMITS.
+
+import { type ComponentType } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import { type DivProps } from '@startupjs-ui/div';
+declare const _default: ComponentType<AvatarProps>;
+export default _default;
+export declare const _PropsJsonSchema: {};
+export interface AvatarProps extends DivProps {
+    /** Custom styles applied to the root view */
+    style?: StyleProp<ViewStyle>;
+    /** Avatar image source URL */
+    src?: string;
+    /** Size preset or explicit pixel value @default 'm' */
+    size?: 's' | 'm' | 'l' | number;
+    /** Status indicator name */
+    status?: 'online' | 'away' | string;
+    /** Avatar shape variant @default 'circle' */
+    shape?: DivProps['shape'];
+    /** Text used to build fallback initials @default '?' */
+    children?: string;
+    /** Custom components for status indicators keyed by status */
+    statusComponents?: Record<string, ComponentType<any>>;
+}

package/index.tsx

@@ -0,0 +1,105 @@
+import { useState, type ComponentType, type ReactNode } from 'react'
+import { Image, type StyleProp, type ViewStyle } from 'react-native'
+import { pug, observer, useDidUpdate } from 'startupjs'
+import { themed } from '@startupjs-ui/core'
+import Div, { type DivProps } from '@startupjs-ui/div'
+import Span from '@startupjs-ui/span'
+import randomcolor from 'randomcolor'
+import STYLES from './index.cssx.styl'
+
+const { config } = STYLES
+
+const DEFAULT_STATUSES = ['online', 'away']
+
+export default observer(themed('Avatar', Avatar))
+
+export const _PropsJsonSchema = {/* AvatarProps */}
+
+export interface AvatarProps extends DivProps {
+  /** Custom styles applied to the root view */
+  style?: StyleProp<ViewStyle>
+  /** Avatar image source URL */
+  src?: string
+  /** Size preset or explicit pixel value @default 'm' */
+  size?: 's' | 'm' | 'l' | number
+  /** Status indicator name */
+  status?: 'online' | 'away' | string
+  /** Avatar shape variant @default 'circle' */
+  shape?: DivProps['shape']
+  /** Text used to build fallback initials @default '?' */
+  children?: string
+  /** Custom components for status indicators keyed by status */
+  statusComponents?: Record<string, ComponentType<any>>
+}
+
+function Avatar ({
+  src,
+  size = 'm',
+  status,
+  shape = 'circle',
+  children = '?',
+  statusComponents,
+  disabled = false,
+  ...props
+}: AvatarProps): ReactNode {
+  const [error, setError] = useState<boolean>()
+  useDidUpdate(() => {
+    setError(undefined)
+  }, [src])
+
+  const _size = config.avatarSizes?.[size] ?? size
+  const _rootStyle = { width: _size, height: _size }
+  const _statusSize = config.statusSizes?.[size] ?? Math.round(Number(size) / 4)
+  const _statusStyle = { width: _statusSize, height: _statusSize }
+  const _fallbackFontSize = config.fallbackSizes?.[size] ?? Math.round(Number(size) / 2.5)
+  const _fallbackStyle = { fontSize: _fallbackFontSize, lineHeight: _fallbackFontSize }
+
+  const StatusComponent = getStatusComponent(statusComponents, status)
+
+  return pug`
+    Div.root(
+      part='root'
+      style=_rootStyle
+      disabled=disabled
+      ...props
+    )
+      Div.avatarWrapper(shape=shape)
+        if src && !error
+          Image.avatar(
+            source={ uri: src }
+            onError=() => {
+              setError(true)
+            }
+          )
+        else
+          - const _fallback = children.trim()
+          - const [firstName, lastName] = _fallback.split(' ')
+          - const initials = (firstName ? firstName[0].toUpperCase() : '') + (lastName ? lastName[0].toUpperCase() : '')
+          Div.avatar(
+            style={backgroundColor: randomcolor({
+              luminosity: 'bright',
+              seed: _fallback
+            })}
+          )
+            Span.fallback(part='fallback' bold style=_fallbackStyle)
+              = initials
+      if status
+        StatusComponent.status(part='status' styleName=[status, shape] style=_statusStyle)
+  `
+}
+
+function getStatusComponent (
+  statusComponents?: AvatarProps['statusComponents'],
+  status?: AvatarProps['status']
+) {
+  if (!status) return Div
+
+  if (!DEFAULT_STATUSES.includes(status) && !statusComponents?.[status]) {
+    console.error(
+      "[@dmapper/ui -> Avatar] Custom component for status '" +
+        status +
+        "' is not specified. Use 'statusComponents' to specify it."
+    )
+  }
+  return statusComponents?.[status] ?? Div
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@startupjs-ui/avatar",
+  "version": "0.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.tsx",
+  "types": "index.d.ts",
+  "type": "module",
+  "dependencies": {
+    "@startupjs-ui/core": "^0.1.3",
+    "@startupjs-ui/div": "^0.1.3",
+    "@startupjs-ui/span": "^0.1.3",
+    "randomcolor": "^0.5.4"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "startupjs": "*"
+  },
+  "gitHead": "fd964ebc3892d3dd0a6c85438c0af619cc50c3f0"
+}