PlTimeline

일이 일어난 순서대로 늘어놓은 단계들입니다. active가 어디까지 왔는지 말하면, timeline이 각 단계의 bullet이 무엇이어야 하는지 계산합니다.

React

import { PlTimeline, PlTimelineItem } from 'plass-ui';

<PlTimeline active={2}>
  <PlTimelineItem title="Ordered" meta="Mon 09:12" bullet="1" />
  <PlTimelineItem title="Packed" meta="Mon 14:40" bullet="2" />
  <PlTimelineItem title="Shipped" meta="Tue 07:05" bullet="3" />
</PlTimeline>;

import 'package:plass_ui/plass_ui.dart';

const PlTimeline(
  active: 2,
  items: <PlTimelineItem>[
    PlTimelineItem(title: Text('Ordered'), meta: Text('Mon 09:12'), bullet: Text('1')),
    PlTimelineItem(title: Text('Packed'), meta: Text('Mon 14:40'), bullet: Text('2')),
    PlTimelineItem(title: Text('Shipped'), meta: Text('Tue 07:05'), bullet: Text('3')),
  ],
);

Props

Prop	타입	기본값	설명
active	number	—	지금 진행 중인 항목의 인덱스. 그 앞은 전부 complete, 그 뒤는 전부 upcoming입니다. 값이 아니라 인덱스인 이유는 timeline에 선택이 없기 때문입니다 — 고르는 것은 없고, 현실이 목록의 어디까지 왔는지만 묻습니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	bullet 지름과 타입 스케일
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	bullet의 그러데이션과 이어진 선의 색 계열
density공통	'default' | 'compact'	'default'	항목 사이의 간격만. 타입 스케일도 bullet도 건드리지 않습니다
orientation공통	PlassResponsive<'horizontal' | 'vertical'>	'vertical'	순서가 흐르는 방향. vertical은 단계 수와 설명 길이에 제한이 없고, horizontal은 결제 화면 위쪽의 stepper라 라벨이 짧을 때만 정직합니다
render	useRender.RenderProp	—	ol이 아닌 다른 요소로 렌더링합니다
children	ReactNode	—	PlTimelineItem들

Prop	타입	기본값	설명
items *	List<PlTimelineItem>	—	단계들. children이 아니라 설명의 목록입니다 — 어느 단계가 끝났는지는 인덱스 계산이고, 마지막 연결선은 자기가 마지막임을 알아야 합니다
active	int?	—	지금 진행 중인 항목의 인덱스. 그 앞은 전부 complete, 그 뒤는 전부 upcoming입니다. 값이 아니라 인덱스인 이유는 timeline에 선택이 없기 때문입니다 — 고르는 것은 없고, 현실이 목록의 어디까지 왔는지만 묻습니다
size공통	PlassSize	PlassSize.md	bullet 지름과 타입 스케일
color공통	PlassColor	PlassColor.primary	bullet의 그러데이션과 이어진 선의 색 계열
density공통	PlassDensity	PlassDensity.standard	항목 사이의 간격만. 타입 스케일도 bullet도 건드리지 않습니다
orientation공통	PlassResponsive<PlassOrientation>	PlassOrientation.vertical	순서가 흐르는 방향. vertical은 단계 수와 설명 길이에 제한이 없고, horizontal은 결제 화면 위쪽의 stepper라 라벨이 짧을 때만 정직합니다

네이티브 <ol> 속성은 그대로 전달됩니다. color는 여기서 Plass의 prop이라 전달 대상에서 제외됩니다.

단계는 children이 아니라 items이고, PlTimelineItem은 위젯이 아니라 설명입니다. PlBreadcrumb과 같은 판단이자 Flutter 자신의 관용구입니다. 어느 단계가 끝났는지는 인덱스 계산이고, 마지막 단계의 연결선은 자기가 마지막임을 알아야 합니다. 불투명한 Widget에는 둘 다 물어볼 수 없습니다.

variant도 elevation도 없습니다. timeline은 페이지 위에 놓인 시트가 아니라 페이지를 따라 내려가는 표시의 줄입니다. 표면이 필요하면 PlCard 안에 넣으세요.

PlTimelineItem

Prop	타입	기본값	설명
title	ReactNode	—	이 단계의 제목
meta	ReactNode	—	언제였는지 — 날짜, 소요 시간, 이름. 넓으면 제목 옆에, 좁으면 그 아래에 놓입니다
bullet	ReactNode	—	bullet 안에 들어가는 것: 숫자, 아이콘, avatar. 생략하면 그냥 원이고, 자기에 대해 할 말이 없는 단계는 그래야 합니다
status	'complete' | 'current' | 'upcoming'	—	timeline의 active가 계산했을 값을 이 항목에 한해 덮어씁니다 — 실패해서 멈춘 단계, 건너뛴 단계
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	—	이 항목에 한해 timeline의 색 계열을 덮어씁니다
connector	'solid' | 'dashed' | 'dotted' | 'none'	'solid'	다음 항목으로 이어지는 선을 어떻게 그릴지. 마지막 항목의 선은 어차피 그려지지 않습니다
children	ReactNode	—	단계의 본문

Prop	타입	기본값	설명
title	Widget?	—	이 단계의 제목
meta	Widget?	—	언제였는지 — 날짜, 소요 시간, 이름. 넓으면 제목 옆에, 좁으면 그 아래에 놓입니다
bullet	Widget?	—	bullet 안에 들어가는 것: 숫자, 아이콘, avatar. 생략하면 그냥 원이고, 자기에 대해 할 말이 없는 단계는 그래야 합니다
status	PlTimelineStatus?	—	timeline의 active가 계산했을 값을 이 항목에 한해 덮어씁니다 — 실패해서 멈춘 단계, 건너뛴 단계
color공통	PlassColor?	—	이 항목에 한해 timeline의 색 계열을 덮어씁니다
connector	PlTimelineConnector	PlTimelineConnector.solid	다음 항목으로 이어지는 선을 어떻게 그릴지. 마지막 항목의 선은 어차피 그려지지 않습니다
child	Widget?	—	단계의 본문

네이티브 <li> 속성은 그대로 전달됩니다. size, density, orientation은 감싸는 PlTimeline에서 상속됩니다.

항목의 인덱스는 속성이 아니고, 될 수도 없습니다. 목록에서 자기가 몇 번째인지 들어야 하는 항목은 모든 호출자가 틀린 자리에 놓을 수 있는 항목이고, 그러면 active는 아무 뜻도 갖지 못합니다. timeline이 단계들을 훑으면서 번호를 매깁니다.

라이브러리 전체에서 공유 축(size color density orientation)이 뜻하는 바는 prop 규칙에 있습니다.

Examples

active

값이 아니라 인덱스인 이유는 timeline에 선택이 없기 때문입니다. 여기서 고르는 것은 없고, 현실이 목록의 어디까지 왔는지만 묻습니다. 생략하면 모든 항목이 upcoming이고, 항목 개수를 넘기면 순서 전체가 끝난 것이 됩니다.

React

import { useState } from 'react';
import { PlButton, PlTimeline, PlTimelineItem } from 'plass-ui';

const steps = ['Account', 'Payment', 'Review', 'Done'];

export default function TimelineActive() {
  const [active, setActive] = useState(1);

  return (
    <div className="flex w-full max-w-md flex-col gap-5">
      <PlTimeline active={active}>
        {steps.map((step) => (
          <PlTimelineItem key={step} title={step} />
        ))}
      </PlTimeline>

      <div className="flex gap-2">
        <PlButton
          size="sm"
          variant="glass"
          color="secondary"
          onClick={() => setActive(Math.max(0, active - 1))}
        >
          Back
        </PlButton>
        <PlButton size="sm" onClick={() => setActive(Math.min(steps.length, active + 1))}>
          Next
        </PlButton>
      </div>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

const List<String> _steps = <String>['Account', 'Payment', 'Review', 'Done'];

class TimelineActive extends StatefulWidget {
  const TimelineActive({super.key});

  @override
  State<TimelineActive> createState() => _TimelineActiveState();
}

class _TimelineActiveState extends State<TimelineActive> {
  int _active = 1;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 448,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        spacing: 20,
        children: <Widget>[
          PlTimeline(
            active: _active,
            items: <PlTimelineItem>[for (final step in _steps) PlTimelineItem(title: Text(step))],
          ),
          Row(
            mainAxisSize: MainAxisSize.min,
            spacing: 8,
            children: <Widget>[
              PlButton(
                size: PlassSize.sm,
                variant: PlassVariant.glass,
                color: PlassColor.secondary,
                onPressed: () => setState(() => _active = _active <= 0 ? 0 : _active - 1),
                child: const Text('Back'),
              ),
              PlButton(
                size: PlassSize.sm,
                onPressed: () => setState(
                  () => _active = _active >= _steps.length ? _steps.length : _active + 1,
                ),
                child: const Text('Next'),
              ),
            ],
          ),
        ],
      ),
    );
  }
}

status

둘이 아니라 셋인 이유는 "지금 있는 곳"이 "끝났다"와 같은 주장이 아니기 때문입니다. 어느 단계가 현재인지 알리지 못하는 순서는 그냥 목록입니다.

각 상태는 불투명도가 아니라 서로 다른 축입니다. complete는 색 계열의 그러데이션, current는 그 그러데이션에 은은한 틴트의 halo, upcoming은 페이지 표면 위의 헤어라인 고리입니다. 색을 구별하지 못하는 독자에게도 채워진 모양, halo가 있는 모양, 빈 모양이 남습니다.

항목의 status는 active가 그 항목에 대해 계산한 값을 덮어씁니다: 실패해서 순서를 멈춘 단계, 건너뛴 단계.

React

import { PlTimeline, PlTimelineItem } from 'plass-ui';

export default function TimelineStatus() {
  return (
    <PlTimeline className="w-full max-w-md" active={3}>
      <PlTimelineItem title="Cloned" bullet="1" />
      <PlTimelineItem title="Installed" bullet="2" />
      <PlTimelineItem title="Tested" bullet="✕" status="upcoming" color="danger">
        Two tests are red, so this step never finished.
      </PlTimelineItem>
      <PlTimelineItem title="Deployed" bullet="4" />
    </PlTimeline>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TimelineStatus extends StatelessWidget {
  const TimelineStatus({super.key});

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 448,
      child: PlTimeline(
        active: 3,
        items: <PlTimelineItem>[
          PlTimelineItem(title: Text('Cloned'), bullet: Text('1')),
          PlTimelineItem(title: Text('Installed'), bullet: Text('2')),
          PlTimelineItem(
            title: Text('Tested'),
            bullet: Text('✕'),
            status: PlTimelineStatus.upcoming,
            color: PlassColor.danger,
            child: Text('Two tests are red, so this step never finished.'),
          ),
          PlTimelineItem(title: Text('Deployed'), bullet: Text('4')),
        ],
      ),
    );
  }
}

connector

선은 채워진 <div>가 아니라 border 한 변으로 그려집니다. 그래서 dashed와 dotted가 브라우저 자신의 점선이고, 라이브러리의 다른 모든 가장자리처럼 기기 픽셀 격자에 정확히 얹힙니다.

Flutter의 BorderSide에는 점선이 없어서 선은 직접 칠합니다. dashed와 dotted는 손으로 놓은 마디들이고, 굵기는 solid와 같습니다. 점은 길이 0인 마디에 둥근 캡을 씌운 것이라, 짧은 사각형이 아니라 원이 됩니다.

선은 도착하는 항목이 아니라 떠나는 항목의 것입니다. 그래서 그 색이 "이 단계에 도달했는가"를 말할 수 있습니다. 마지막 항목의 선은 그려지지 않습니다. 순서 밖 아무것도 없는 곳으로 달려 나가게 되기 때문입니다.

React

import { PlTimeline, PlTimelineItem } from 'plass-ui';

export default function TimelineConnectors() {
  return (
    <PlTimeline className="w-full max-w-md" density="compact" active={4}>
      <PlTimelineItem title="solid" connector="solid" />
      <PlTimelineItem title="dashed" connector="dashed" />
      <PlTimelineItem title="dotted" connector="dotted" />
      <PlTimelineItem title="none" connector="none" />
      <PlTimelineItem title="The last line is never drawn" />
    </PlTimeline>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TimelineConnectors extends StatelessWidget {
  const TimelineConnectors({super.key});

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 448,
      child: PlTimeline(
        density: PlassDensity.compact,
        active: 4,
        items: <PlTimelineItem>[
          PlTimelineItem(title: Text('solid')),
          PlTimelineItem(title: Text('dashed'), connector: PlTimelineConnector.dashed),
          PlTimelineItem(title: Text('dotted'), connector: PlTimelineConnector.dotted),
          PlTimelineItem(title: Text('none'), connector: PlTimelineConnector.none),
          PlTimelineItem(title: Text('The last line is never drawn')),
        ],
      ),
    );
  }
}

orientation

기본값 vertical은 단계 수에도, 각 단계에 대해 할 말의 양에도 제한이 없습니다. horizontal은 결제 화면 위쪽을 가로지르는 stepper이고, 모든 라벨이 짧을 때만 정직합니다.

반응형입니다. 그래서 한 집합이 폰에서는 이쪽으로, 노트북에서는 저쪽으로 갈 수 있습니다. 서버는 xs 항목을 렌더링하고 브라우저가 hydration에서 고칩니다.build에서 창 너비를 기준으로 풀리므로 첫 프레임부터 정확합니다. 브레이크포인트 참고.

React

import { PlTimeline, PlTimelineItem } from 'plass-ui';

export default function TimelineOrientation() {
  return (
    <PlTimeline className="w-full max-w-lg" orientation="horizontal" active={1}>
      <PlTimelineItem title="Account" bullet="1" />
      <PlTimelineItem title="Payment" bullet="2" />
      <PlTimelineItem title="Review" bullet="3" />
      <PlTimelineItem title="Done" bullet="4" />
    </PlTimeline>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TimelineOrientation extends StatelessWidget {
  const TimelineOrientation({super.key});

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 512,
      child: PlTimeline(
        orientation: PlassResponsive<PlassOrientation>(PlassOrientation.horizontal),
        active: 1,
        items: <PlTimelineItem>[
          PlTimelineItem(title: Text('Account'), bullet: Text('1')),
          PlTimelineItem(title: Text('Payment'), bullet: Text('2')),
          PlTimelineItem(title: Text('Review'), bullet: Text('3')),
          PlTimelineItem(title: Text('Done'), bullet: Text('4')),
        ],
      ),
    );
  }
}

size

React

import { PlTimeline, PlTimelineItem } from 'plass-ui';

export default function TimelineSizes() {
  return (
    <div className="flex w-full max-w-lg flex-wrap gap-8">
      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((size) => (
        <PlTimeline key={size} size={size} density="compact" active={1}>
          <PlTimelineItem title={size} bullet="1" />
          <PlTimelineItem title="Next" bullet="2" />
        </PlTimeline>
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TimelineSizes extends StatelessWidget {
  const TimelineSizes({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 512,
      child: Wrap(
        spacing: 32,
        runSpacing: 32,
        children: <Widget>[
          for (final size in PlassSize.values)
            SizedBox(
              width: 200,
              child: PlTimeline(
                size: size,
                density: PlassDensity.compact,
                active: 1,
                items: <PlTimelineItem>[
                  PlTimelineItem(title: Text(size.name), bullet: const Text('1')),
                  const PlTimelineItem(title: Text('Next'), bullet: Text('2')),
                ],
              ),
            ),
        ],
      ),
    );
  }
}

Accessibility

• 이것이 존재하는 이유 그대로 <ol>입니다. 순서가 곧 내용입니다. 순서 없는 목록 위에서 "5개 항목 목록"이라고 읽는 스크린리더는 다른 것을 설명하고 있는 셈입니다.
• role="list"를 명시적으로 씁니다. Tailwind의 리셋이 모든 <ol>에서 마커를 없애고, Safari는 그와 함께 목록 의미까지 없애기 때문입니다.
• 현재 단계는 aria-current="step"을 답니다. 순서에 맞는 값이 그것입니다. "page"는 문서의 자취이고 "true"는 선택지 중 하나입니다.
• bullet과 연결선은 aria-hidden입니다. 상태는 aria-current와 각 단계의 글에 담기고, 모양만으로 전달되지 않습니다.
• 아래에 Base UI 프리미티브가 없습니다. timeline에는 선택도, roving focus도, 키보드 규약도 없고, 복합 프리미티브를 끌어오면 사건의 기록에 위젯의 의미를 붙이게 됩니다.

• 단계는 순서대로 읽힙니다. 그것이 이 순서열이 가진 전부입니다. 각 단계는 자기 노드입니다.
• bullet과 연결선은 semantics에서 제외됩니다. 숫자로 그려진 bullet은 단계의 제목이 이미 알리지 않는 것을 스크린리더에 더해 주지 않습니다.
• 알아 둘 만한 결과가 여기 있습니다. 상태는 스크린리더에 전달되지 않습니다. Flutter의 semantics 트리에는 순서열을 위한 current가 없으므로, 끝난 단계와 남은 단계가 같은 방식으로 읽힙니다. 상태가 중요한 자리라면 말로 하세요: 단계의 meta에, 또는 본문에.
• timeline에는 선택도, roving focus도, 키보드 규약도 없고, 그런 것을 주장하지도 않습니다.

React 빌드와 다른 점

React	Flutter	이유
<PlTimelineItem> children	설명으로서의 items	어느 단계가 끝났는지는 인덱스 계산이고, 마지막 연결선은 자기가 마지막임을 알아야 합니다. 둘 다 Widget에는 물어볼 수 없습니다.
aria-current="step"	—	Flutter의 semantics 트리에는 current가 없습니다. 상태가 중요한 자리에서는 단계의 글로 말하세요.
<ol>과 role="list"	묶인 semantics 노드	리셋할 마커도, 리셋이 앗아 갈 목록 의미도 없습니다.
dashed/dotted인 border	칠해진 선	BorderSide에는 점선이 없어서, 마디를 같은 굵기로 직접 놓습니다.
render	—	Flutter에는 요소를 바꿔 끼우는 수단이 없습니다.
단계의 children	child	Flutter의 이름입니다.